From 6e283d16c31ffdd8b6aafb9d4f35562ebe8c609c Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Thu, 8 Oct 2026 13:56:36 +0000 Subject: [PATCH] Plan the ReleaseKit adoption --- docs/roadmap/implementation.md | 377 +++++++++++++++++++++++++++++++++ docs/roadmap/releasekit.md | 5 +- 2 files changed, 379 insertions(+), 3 deletions(-) create mode 100644 docs/roadmap/implementation.md diff --git a/docs/roadmap/implementation.md b/docs/roadmap/implementation.md new file mode 100644 index 0000000..2d3614b --- /dev/null +++ b/docs/roadmap/implementation.md @@ -0,0 +1,377 @@ +# ReleaseKit Adoption Implementation Plan + +Implement the agreed [adoption roadmap](releasekit.md) in the stages below, +in order. Each stage is scoped for one Luna coding-agent prompt. This document +owns the implementation steps; the roadmap owns purpose and selected policy. + +## Baseline And Working Rules + +- Planning baseline: PromptKit commit + `41b2021d8cd90b8dc15483f63fb1979642acad3a`. ReleaseKit is not yet a dependency; + publication and validation live in `scripts/release.sh` and + `scripts/release-check.sh`. +- Select released ReleaseKit `v0.2.0`, whose commit is + `e030794969fb7787e647a90bbc4eb81bd0610f07`. Use its + [profile](https://gitea.maximumdirect.net/eric/ReleaseKit/src/tag/v0.2.0/docs/config.md), + [CLI](https://gitea.maximumdirect.net/eric/ReleaseKit/src/tag/v0.2.0/docs/cli.md), + and [candidate validation](https://gitea.maximumdirect.net/eric/ReleaseKit/src/tag/v0.2.0/docs/consumers/check.md) + contracts. No upstream changes or sibling-checkout dependency are needed. +- Start with [development](../development.md), then read the + [agent](../policy/agents.md) policy and applicable + [architecture](../policy/architecture.md), + [testing](../policy/testing.md), + [documentation](../policy/documentation.md), + [release](../policy/release.md), and [OSS](../policy/oss.md) policies. + Reuse already-read, unchanged policies and preserve unrelated work. +- Inspect current files before each stage. Validate and commit each completed + unit under the agent policy. Follow later explicit user instructions about + commits if they differ. +- All Git publication during implementation verification targets disposable + local remotes. Implementing this plan does not authorize publishing to + PromptKit's actual origin, creating a real release tag, or modifying ReleaseKit. +- Keep PromptKit's runtime API and business logic unchanged. The approved Go + requirement update and tool dependency are module changes, not runtime + ReleaseKit integration. +- Retain source-only publication, the main-before-tag workflow, and completion + at confirmed tag publication. Hosted pages and CI deployment are outside + this adoption. Retire the credential regex without adding a replacement gate. +- Use the latest Go installation available in the development environment. + Activate it as `go`, set `GOTOOLCHAIN=local`, and use it for tool builds, + candidate tests, and examples. At planning time the active local version is + `go1.26.8`; derive the version during implementation instead of freezing it + in scripts. Do not query `go@latest` or download another toolchain to find it. +- Keep dependency preparation separate from offline validation. Reuse successful + checks for unchanged content; do not add parallel validators, a persistent + validation cache, or additional human release sign-offs. + +## Stage 1 — Declare The Released Tool And Advance The Go Requirement + +**Outcome:** Module metadata selects ReleaseKit as a maintainer tool and records +the development environment's current Go requirement. + +**Read:** `go.mod`, `go.sum`, the runbook's +[preparation step](../release.md#prepare-the-candidate), and the OSS policy. + +**Changes:** + +1. From the repository root, use the active latest local Go installation: + `export GOTOOLCHAIN=local`; capture `go env GOVERSION`. +2. Advance the requirement with + `go get "go@${release_go_version#go}"`, where `release_go_version` contains + that captured value. This is preparation before the resulting candidate + commit, not an operation performed inside publication. +3. Add the tool with + `go get -tool gitea.maximumdirect.net/eric/ReleaseKit/cmd/releasekit@v0.2.0`. + Use a Go `tool` declaration, not an artificial runtime import or a + `tools.go` workaround. +4. Prepare dependencies with `GOTOOLCHAIN=local go mod download`. Review the + module and checksum changes; retain necessary tool/transitive dependencies + without opportunistic unrelated upgrades. +5. Apply the OSS policy according to actual use. This is tool-only use, with + no copied ReleaseKit implementation or documentation; that alone requires + no new attribution entry. If a necessary existing dependency selection + changes, maintain its applicable existing notices in this unit. +6. Preserve repository independence: no committed workspace or local + filesystem replacement. Do not select a PromptKit release version or write + a prospective versioned release note in this stage. + +**Verification:** + +- `GOTOOLCHAIN=local go list -m gitea.maximumdirect.net/eric/ReleaseKit` identifies + `v0.2.0`; module metadata declares the intended tool. +- Run `GOTOOLCHAIN=local go test -mod=readonly ./...` for the Go/module change. +- Inspect `go list -deps .` to confirm the runtime facade has no ReleaseKit + import dependency. Review the diff and commit the unit. + +## Stage 2 — Extract The Consumer Check And Declare Shared Validation + +**Outcome:** One focused example checker and one profile express the selected +validation without changing the publication entry point yet. + +**Read:** The example-assertion block in `scripts/release-check.sh`, the three +maintained examples, the testing policy, and ReleaseKit's profile reference. + +**Changes:** + +1. Create `scripts/check-examples.py`, runnable as + `python3 scripts/check-examples.py`. Use Python's standard library, derive + the repository root from the script location, and run from that root. +2. Move the existing semantic assertions into that checker. Preserve all current + expectations: preparation ID/profile/model/message count; execution output, + validity, validation status, model and token count; observation attempt/retry + counts, usage completeness, and accepted assessment outcome. +3. Execute each example once, parse its JSON, propagate compilation/process and + assertion failures as nonzero results, and provide useful failure context. + Keep the checker narrow; it does not run tests, vet, formatting, links, + module inspection, or publication. +4. Use the selected local Go installation for example execution. Set native + host `GOOS`/`GOARCH` from that installation's `go env GOHOSTOS GOHOSTARCH` + for the example children so ambient cross-build settings do not select an + unexecutable target. Keep normal native cgo/cache settings. +5. Create root `releasekit.json` with these exact selections: + + | Profile field | Value | + | --- | --- | + | `product` | `"Promptkit"` | + | `remote` | `"origin"` | + | `validation.go.race` | `true` | + | `validation.go.full_vet` | `true` | + | `validation.go_format` | `true` | + | `validation.markdown` | `{}` | + | `validation.module_distribution.workspace_files` | `true` | + | `validation.module_distribution.local_replacements` | `true` | + + Set `checks` to one command whose argument vector is + `["python3", "./scripts/check-examples.py"]`. Its environment map selects + `GOTOOLCHAIN=local`, `GOWORK=off`, `GOFLAGS=-mod=readonly`, + `GOPROXY=off`, `GONOPROXY=none`, and `GOSUMDB=off`. These settings apply to + the additional check; ReleaseKit owns its own shared Go environment. +6. Omit `build`, `delivery`, `expected_push_url`, package-compilation targets, + file-size selection, and Markdown boundary enforcement. Accept the upstream + default out-of-scope handling for outside-checkout Markdown destinations. +7. Add a concise standalone example-check command to the development guide. + Keep the existing publication/checker documentation until the cutover. + +**Verification:** + +- Run the new example checker using the offline environment above. +- Check profile JSON syntax and the selected fields against the released + reference. Detailed API/profile equivalence tests belong upstream. +- Review the extracted assertions against the old block, then commit. + +## Stage 3 — Add The Native Tool Bootstrap + +**Outcome:** A small shared invocation script builds and runs the module-selected +native executable. Legacy source publication remains active until Stage 6. + +**Read:** `.gitignore`, the new module declaration and profile, and the +upstream CLI contract. + +**Changes:** + +1. Create executable POSIX-shell `scripts/releasekit.sh`. Its role is: + enter its repository root, build the declared tool, and invoke the native + executable with the supplied CLI arguments. +2. Use `set -eu`, `GOTOOLCHAIN=local`, `GOWORK=off`, and + `GOFLAGS=-mod=readonly`. Build + `gitea.maximumdirect.net/eric/ReleaseKit/cmd/releasekit` with + `go build -mod=readonly` into `.releasekit/bin/releasekit`. + Select the native host `GOOS`/`GOARCH` for that build using the active Go + installation's host values. +3. Rebuild through Go's normal build cache on each invocation. This ensures the + executable uses the active Go compiler and module selection, without a + custom cache/version-validation protocol. +4. Use `exec` to invoke the built executable and forward `"$@"` unchanged. + Delegate command/version parsing, candidate guards, and exit classifications + to ReleaseKit. Do not use `go run` for publication. +5. Ignore the root `.releasekit/` directory. Do not commit the built tool or + describe it as a PromptKit binary deliverable. +6. Bootstrap may use ordinary module access if preparation has not populated + caches, while readonly mode preserves module files. Candidate validation and + examples remain offline. Bootstrap does not edit the Go requirement, fetch + Git refs itself, create tags, or add publication guards. +7. Add an optional diagnostic `./scripts/releasekit.sh check VERSION` invocation + to the current runbook, linked to upstream requirements for a committed + candidate. Make clear it is not required before publication. + +**Verification:** + +- Run `sh -n scripts/releasekit.sh`. +- Run `./scripts/releasekit.sh version`; inspect the executable with + `go version -m` to confirm its recorded Go build version matches the selected + installation and its module selection is the released ReleaseKit. +- Check that bootstrap leaves `go.mod`/`go.sum` unchanged and the tool output + ignored. No real publication is performed. Commit. + +## Stage 4 — Add A Small Successful Publication Fixture + +**Outcome:** A standalone offline integration check protects local bootstrap, +profile wiring, and successful source publication. + +**Read:** The production profile/bootstrap, the testing policy, and the +upstream source-publication contract. + +**Changes:** + +1. Create `scripts/test-release.py`, invoked explicitly with Python 3 during + tooling development. Keep it outside the default Go suite and outside the + profile's release checks. It is not a new per-release gate. +2. Use standard-library temporary directories and subprocesses with real Git + and the released tool. Use a synthetic working repository on `main` and a + local bare `origin`; all identities and release versions are fixture data. +3. Copy the production bootstrap, profile, and relevant ignore rule into the + fixture. Copy the selected `go.mod`/`go.sum` so tool selection follows + production metadata without a local replacement. +4. Add a tiny formatted Go package and test. The test writes an invocation + marker outside the checkout and records `runtime.Version()`. Use small + race/non-race build-tag files so the test can prove the selected suite was + race-enabled. This fixture never imports or retests PromptKit's full library. +5. At the configured example-check path, install a fixture-only Python stand-in + that writes an external invocation marker. Keep the real profile command + and validation selections unchanged. Stage 2 verifies the real examples; + this fixture verifies additional-check wiring. +6. Add a simple version-matched release note, commit the fixture, and push its + `main` to the local bare remote. Run the copied bootstrap's `publish` + command from outside the fixture's repository root to exercise path handling. +7. Keep the test invocation offline with prepared module caches, + `GOTOOLCHAIN=local`, `GOPROXY=off`, `GONOPROXY=none`, and `GOSUMDB=off`. + Format generated Go files before committing them. +8. Assert native status 0, exactly one suite marker and one additional-check + marker, and equal selected/tool-build/test Go versions. Verify that the + local and remote tag are annotated and identify the fixture candidate, + with the committed note as annotation. Confirm module bytes are unchanged + and the fixture remains clean apart from ignored tool output. + +**Verification:** + +- Run `python3 scripts/test-release.py` after dependency preparation. +- Inspect that fixtures and markers use only temporary paths/local remotes. +- Do not add upstream's full tag/recovery/checker matrix or test framework. + Commit the focused success-path test. + +## Stage 5 — Cover Local Failure Propagation + +**Outcome:** The same fixture demonstrates that failed product validation cannot +publish a tag and that native argument failures remain classified. + +**Read:** Stage 4's fixture and ReleaseKit's CLI exit classifications. + +**Changes:** + +1. Extend the fixture stand-in to select failure through a test-owned + environment value. In a fresh candidate/version, let shared validation pass + and then fail that additional check. +2. Assert nonzero native publication status 1, one suite and one additional-check + invocation, useful failure context, and no selected tag locally or remotely. + Keep the fixture clean and module metadata unchanged. +3. Add one malformed/unsupported invocation case that exercises native status 2. + Check the classification and a useful diagnostic fragment, not a complete + output snapshot. +4. Reuse the small fixture setup and production profile. Do not simulate CI, + live push errors, uncertain-write reconciliation, hosted delivery, or + malicious concurrent mutation; those are upstream responsibilities. +5. Preserve cleanup of the temporary repositories and external markers. + Failures must not modify the actual PromptKit checkout or its remote. + +**Verification:** + +- Run the completed standalone integration check. +- Review coverage for the three risks: successful wiring, failed additional + validation, and native usage classification. Commit. + +## Stage 6 — Cut Over Publication And Its Canonical Documentation + +**Outcome:** One publication command uses ReleaseKit; obsolete local validators +and their documented gates are retired in the same unit. + +**Read:** `scripts/release.sh`, `scripts/release-check.sh`, the released CLI +and recovery guidance, and the affected canonical documentation. + +**Changes:** + +1. Replace `scripts/release.sh` with a thin executable wrapper that delegates to + `scripts/releasekit.sh publish`, forwarding supplied arguments through + `exec`. Keep the familiar `./scripts/release.sh VERSION` entry point. + Add no duplicate argument, branch, remote, note, tag, or status machinery. +2. Delete `scripts/release-check.sh`. The shared suite, vet, formatting, + Markdown parser, and module checks now belong to ReleaseKit. The example + assertions already have their focused owner. +3. Remove the credential-pattern gate, clean-candidate diff-whitespace gates, + ambient-workspace rejection, blanket vendor-path check, blanket replacement + prohibition, mandatory four-heading note validator, and extra annotation + commit line. Retain ordinary credential-aware change review and useful + development `git diff --check` commands. +4. Update `scripts/test-release.py` to copy and invoke the actual + `scripts/release.sh` entry point for publication cases. The generic native + invocation can continue to own the CLI classification case. +5. Update `docs/policy/release.md` locally where needed: + shared selections, source-only deliverables, main-before-tag publication, + the simpler note convention, native recovery states, and retired gates. + Preserve SemVer/compatibility rules, immutable records, catalog exceptions, + the Go-update/same-toolchain requirement, and successful-tag-push completion. + Preserve upstream provenance/base-policy metadata; update the local date. +6. Update `docs/policy/testing.md` to describe selected race/full vet and + consumer workflows, with shared machinery upstream. Document the standalone + wiring check as focused development validation, not a recurring release + requirement or part of default Go tests. +7. Rewrite the relevant `docs/release.md` sections around: + activate the latest available local Go; update its requirement before the + candidate commit; prepare module caches; author the note/footer; retire + completed roadmaps; ordinary review/commit; push `main`; run the single + publication command. Preparation commands may update module metadata before + commit; bootstrap/validation preserve the final candidate. +8. Document native statuses 0/1/2/3 and the upstream captured-endpoint recovery + model. Link to upstream detail and include a concise usable recovery command. + Never resolve uncertainty by deleting a tag before confirming authoritative + absence. No CI wait, successful-push read-back, or installation check is added. +9. Update `docs/development.md`: remove the old checker command/inventory and + scanner reference; retain proportionate tests, formatting, examples and + ordinary review for dirty development work. Identify the optional committed + candidate diagnostic and the separate tooling integration command. +10. Repair links to the removed checker. Keep existing historical release notes, + licenses, runtime inventory, and public API documentation unchanged unless + a concrete affected reference requires correction. No prospective release + note, hosted workflow, or new consumer restriction is part of this unit. + +**Verification:** + +- Run `sh -n` on the two wrappers and the completed integration check using the + final publication entry point. +- Review the diff for policy/procedure agreement and removal of the listed + duplicate gates. Check links and whitespace without running a second complete + package suite solely for these documentation edits. Commit the cutover. + +## Stage 7 — Verify The Actual Profile Against The Complete Source Snapshot + +**Outcome:** The assembled adoption is verified without publishing a real +PromptKit release. + +**Read:** The final roadmap, profile, wrappers, runbook, and this plan's +completion criteria. + +**Work:** + +1. Confirm prior stages are committed and the working checkout is clean. + Use the same active local Go installation and prepared module cache. +2. Make a disposable local clone of the final committed PromptKit source, + checkout `main`, and add/commit only a synthetic unused version's release + note there. The note follows the adopted product/version convention and + footer paths. Do not add that note to the actual checkout. +3. Run the clone's `scripts/releasekit.sh check VERSION` with the real profile + and actual example checker. This is the one complete final smoke check: + the real race-enabled suite, full vet, formatting, Markdown, committed + distribution checks, and three examples. Do not also run the old full + checker or another full test/vet/example sequence for that same snapshot. +4. Confirm module files remain unchanged, actual example checks succeed, + shared Markdown/format checks inspect the final source, and the clone remains + clean. This local `check` creates no tag and needs no remote publication. +5. If supported upstream checks expose affected formatting or documentation + defects, correct those specific issues and commit the changed candidate + before repeating the snapshot check. Do not disable the selected validation + to make the smoke check pass. +6. Audit completion against the roadmap: module tool selection, native/same-Go + bootstrap, all six optional validation selections, one local example check, + retired validators/gates, accurate runbooks/policies, and successful fixture + publication/failure protection. Reuse Stage 6's unchanged integration results. +7. Report the implementation commits, checks, and any remaining issues. Update + temporary roadmap/plan status to reflect implemented work awaiting review; + keep the documents available for the user's review. Release preparation and + completed-roadmap retirement remain later maintainer work. + +**Completion criteria:** + +- The final source-only publication command delegates to released ReleaseKit; + the committed profile is the single local declaration of selected checks. +- Go metadata records the preparation-time requirement; tool build, native + validation and examples use the same selected local Go installation. +- Profile-selected shared validation and the real consumer examples pass on the + complete source snapshot, while fixture failures prevent publication. +- No runtime ReleaseKit import, local module replacement, extra release gate, + hosted workflow, provider call, real origin push, or real release tag has + been introduced. +- Canonical docs agree with implemented tooling and preserve the accepted + compatibility, catalog, licensing-footer and release-completion policies. + +No significant product decisions remain open. Implementation choices above +settle the filenames, bootstrap, profile, validation boundaries, and test +strategy needed to carry out the agreed scope. diff --git a/docs/roadmap/releasekit.md b/docs/roadmap/releasekit.md index a4f34d1..b63d9cf 100644 --- a/docs/roadmap/releasekit.md +++ b/docs/roadmap/releasekit.md @@ -1,7 +1,7 @@ # ReleaseKit Adoption Roadmap Status: Adoption scope agreed; implementation has not started. -A companion staged implementation plan will define the implementation steps. +The [implementation plan](implementation.md) owns the ordered migration steps. ## Purpose @@ -239,5 +239,4 @@ workflow. Source-publication testing requires no provider credentials or live inference. The desired reduction is in owned machinery and routine decisions, not a -fixed deletion count. The companion implementation plan will divide this -migration into appropriately scoped stages. +fixed deletion count.