eric/promptkit
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Plan the ReleaseKit adoption

Browse Source
This commit is contained in:
Eric Rakestraw
2026-10-08 13:56:36 +00:00
parent 41b2021d8c
commit 6e283d16c3
2 changed files with 379 additions and 3 deletions
Download Patch File Download Diff File Expand all files Collapse all files

377
docs/roadmap/implementation.md Normal file
View File

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