From a148a2b1f46c6565743cb068bf33d2142d3133e3 Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Thu, 8 Oct 2026 13:13:10 +0000 Subject: [PATCH] Define the ReleaseKit adoption roadmap --- docs/roadmap/releasekit.md | 427 ++++++++++++++++++------------------- 1 file changed, 202 insertions(+), 225 deletions(-) diff --git a/docs/roadmap/releasekit.md b/docs/roadmap/releasekit.md index 08c9cc3..b94f5bb 100644 --- a/docs/roadmap/releasekit.md +++ b/docs/roadmap/releasekit.md @@ -1,276 +1,253 @@ -# ReleaseKit Adoption Assessment +# ReleaseKit Adoption Roadmap -Status: Recommendations for review. Release tooling and adopted policies have -not changed. This assessment is the basis for a later feature roadmap and -implementation plan. +Status: Adoption scope for review; implementation has not started. +A companion staged implementation plan will define the implementation steps. -## Purpose And Evaluation Standard +## Purpose -Adopt ReleaseKit to standardize PromptKit's release process and reduce the -amount and complexity of release code maintained here. Prefer the shared -workflow over reproducing every existing local behavior. Retain local checks -where they protect a substantive project requirement; propose broadly useful -validation upstream where doing so saves continuing maintenance. +Adopt ReleaseKit's common release workflow and move reusable release +validation and publication mechanics upstream. PromptKit should maintain +product settings, release-note content, and substantive consumer checks, +with little release orchestration of its own. -Changes to release mechanics are acceptable. Their value should be assessed -against the [release policy](../policy/release.md), -[testing policy](../policy/testing.md), and the user's preference for few, -automated, nonredundant gates. Existing local release checks are evidence to -evaluate, rather than a requirement to preserve them all. +Changes to existing release mechanics are an acceptable trade-off for +standardization and lower maintenance. Prefer supported upstream conventions +over preserving incidental local behavior. The +[release policy](../policy/release.md), +[testing policy](../policy/testing.md), and +[agent policy](../policy/agents.md) govern the migration; policy changes belong +in the implementation alongside the new workflow. -This document recommends future changes. The current -[release procedure](../release.md) remains authoritative until adoption lands. +## Baseline And Available Upstream Support -## Reviewed Baseline +The current PromptKit baseline is commit +`7310ef34a44dae7288db7b281e2a6b7f2c56c4e9`. Its implemented +[release procedure](../release.md) uses `scripts/release.sh` for publication +and `scripts/release-check.sh` for validation. The scripts contain 209 lines +and own publication guards, testing, vet, example assertions, formatting, +Markdown links, module checks, whitespace checks, and a credential regex. +There is no ReleaseKit dependency or hosted delivery workflow. -Assessment date: 2026-10-07. +The earlier +[adoption assessment](https://gitea.maximumdirect.net/eric/promptkit/src/commit/7310ef34a44dae7288db7b281e2a6b7f2c56c4e9/docs/roadmap/releasekit.md) +is preserved in Git history. This roadmap supersedes its recommendations +where the released upstream capabilities change the available choices. -- PromptKit: commit `4b8169da286917fde7875425bb32b799b12c6af3`, with a clean - worktree before this assessment. Its release scripts contain 209 lines: - 57 in [publication](../../scripts/release.sh) and 152 in - [validation](../../scripts/release-check.sh). -- ReleaseKit: published `v0.1.0`, commit - `5e60fe3113c69f95c42fbbe32a8ca4b51f5b83c1`. The local checkout and upstream - `main` match the tag's peeled commit. See its - [configuration reference](https://gitea.maximumdirect.net/eric/ReleaseKit/src/commit/5e60fe3113c69f95c42fbbe32a8ca4b51f5b83c1/docs/config.md), - [publication guide](https://gitea.maximumdirect.net/eric/ReleaseKit/src/commit/5e60fe3113c69f95c42fbbe32a8ca4b51f5b83c1/docs/consumers/publish.md), - and [CLI contract](https://gitea.maximumdirect.net/eric/ReleaseKit/src/commit/5e60fe3113c69f95c42fbbe32a8ca4b51f5b83c1/docs/cli.md). -- The preceding review ran ReleaseKit's offline Go suite successfully. Its - tests use local Git remotes and HTTP fixtures for publication and delivery; - this is not evidence of a live PromptKit integration or deployed delivery - workflow. No candidate was published as part of either review. +Adopt the published ReleaseKit `v0.2.0` baseline, commit +`e030794969fb7787e647a90bbc4eb81bd0610f07`. Its public API and profile provide +all four primary requested capabilities and module-distribution checks. +The reviewed release's full offline test suite passed. PromptKit's actual +integration still needs validation during implementation. -The assessment examined both release scripts, their owning documentation, -ReleaseKit's candidate and publication behavior, additional-check execution, -and its controlled Go environment. Installed `go help test` confirms that -ordinary `go test` includes a subset of vet's default analyses. +The upstream owners of the adopted behavior are: -## Overall Fit +- [ReleaseKit configuration](https://gitea.maximumdirect.net/eric/ReleaseKit/src/tag/v0.2.0/docs/config.md). +- [Candidate validation](https://gitea.maximumdirect.net/eric/ReleaseKit/src/tag/v0.2.0/docs/consumers/check.md). +- [Source publication](https://gitea.maximumdirect.net/eric/ReleaseKit/src/tag/v0.2.0/docs/consumers/publish.md). +- [CLI behavior](https://gitea.maximumdirect.net/eric/ReleaseKit/src/tag/v0.2.0/docs/cli.md). +- [Module-selected tooling decision](https://gitea.maximumdirect.net/eric/ReleaseKit/src/tag/v0.2.0/docs/adr/0004-module-selected-tooling.md). -ReleaseKit already owns stable-version parsing, committed release-note -capture, a clean candidate on `main`, unused local and authoritative remote -tags, exact candidate identity, annotated-tag creation, publication, and -bounded reconciliation after a failed push. PromptKit already uses the same -main-before-tag publication model. ReleaseKit can replace those mechanics -without a PromptKit-owned orchestration package. +No further upstream feature work is needed for the proposed source-publication +scope. -Its standard candidate suite is -`go test -mod=readonly -count=1 ./...`. It uses the available compatible local -Go toolchain, disables workspace discovery and module/toolchain downloads for -that run, and controls settings that could change the selected tests or host -target. Dependency and tool installation belong to preparation. Additional -check commands are separate children; they do not automatically inherit that -entire controlled Go environment. +## Target End State -Successful source publication remains the completion point. The native CLI -also reports known failures, conflicts, and uncertain pushes. PromptKit can -use that recovery model directly, including querying the captured publication -endpoint when needed. Neither CI success nor consumer installation becomes a -release gate. +### Tool Selection And Local Ownership -## Assessment Of Existing Checks +PromptKit declares `gitea.maximumdirect.net/eric/ReleaseKit/cmd/releasekit` +as a Go tool dependency, initially selecting ReleaseKit `v0.2.0` through +its module configuration. That selection is the version source for local +release tooling and any later module-based delivery integration. -| Current check or responsibility | Recommendation | Reason and ownership | +A small `releasekit.json` profile declares product identity, the publication +remote, shared validation choices, and the PromptKit-specific example check. +Use `Promptkit` as the product value to match existing release-note titles, +with `main` and `origin` as the release branch and remote. + +The existing publication entry point becomes a thin wrapper that prepares +and invokes the module-selected native ReleaseKit executable. Native +publication exit classifications remain available, including an uncertain +push result. Tool bootstrap and dependency preparation precede offline +candidate validation. The wrapper's responsibility is tool invocation; +ReleaseKit owns candidate guards, validation coordination, tags, and recovery. + +Tool output stays outside committed source, and preparation preserves the +candidate's module files. The library's supported runtime API and execution +logic need no changes. Tool declarations affect the module graph without +adding a ReleaseKit runtime import or a PromptKit release-orchestration package. + +### Shared Validation Selection + +Select the following capabilities through the ReleaseKit profile: + +| Capability | Target selection | Purpose | | --- | --- | --- | -| Stable SemVer, clean `main`, unused version, synchronized authoritative branch, and candidate rechecks | Adopt ReleaseKit. | These are shared publication mechanics, already implemented and tested upstream. Remove the local equivalents. | -| Annotated tag, release-note annotation, and explicit tag-only push | Adopt ReleaseKit. | Use the committed note as the annotation. The extra `Validated commit` annotation line is unnecessary: the tag already identifies that commit. | -| Failed or ambiguous push recovery | Adopt ReleaseKit. | Its bounded reconciliation and reported endpoint replace local recovery mechanics. Retain a short maintainer runbook linked to the upstream contract. | -| Full Go test suite | Adopt the shared standard suite once. | Remove the suite invocation from additional checks. A separate `check` invocation before `publish` is diagnostic, not a required second pass. | -| Race detector | Seek a shared race-enabled standard-suite variant; resolve Open Question 1. | PromptKit has real concurrent execution and capacity management. Race detection offers distinct protection, but the current upstream suite cannot enable it. Do not attach a second complete test run just to preserve the old command. | -| Explicit `go vet ./...` | Retain as a configured command pending Open Question 2. | Ordinary `go test` runs only a subset of vet analyses. Full vet is not wholly redundant, although part of its work overlaps. Its invocation needs no custom local implementation. | -| Three offline consumer examples with semantic JSON assertions | Retain locally as a focused additional check. | Expected preparation, execution, retry, validation, and usage results are PromptKit-specific. Preserve these assembled consumer workflows without moving their expected values into ReleaseKit. | -| Tracked Go formatting | Propose shared upstream support. | Enumerating source files, invoking `gofmt`, and reporting unformatted files are reusable mechanics. Select this check for PromptKit without maintaining its shell loop here. | -| Local Markdown paths and heading fragments | Propose shared upstream support. | This is the largest generic block in the checker. Offline broken-link detection protects documentation consumers across repositories. Replace the local parser with supported upstream behavior. | -| Rejection of an ambient active Go workspace | Remove this release gate. | ReleaseKit already runs its standard suite with workspace discovery disabled. Apply suitable settings to additional Go commands as well; an unrelated active workspace need not prevent release. | -| Tracked `go.work` and `go.work.sum` | Retain the project rule through a small additional check. | The [architecture policy](../policy/architecture.md#repository-independence) expressly keeps workspace files out of PromptKit's committed source. Disabling discovery does not enforce that distribution rule. | -| Blanket rejection of every `replace` directive | Narrow to the established project requirement. | Architecture prohibits local filesystem replacements. A versioned module replacement is different; the current blanket check is broader than that stated requirement. Do not export the blanket ban as a shared standard. | -| Rejection whenever a `vendor` path exists | Remove the blanket release gate. | The architecture policy does not establish this prohibition. ReleaseKit's standard `-mod=readonly` run avoids automatic vendor selection; a local ignored directory need not block it. Review any intentional distribution change through ordinary development. | -| `git diff --check` and its staged counterpart | Keep in ordinary development; remove as release gates. | A clean, committed release candidate has no staged or unstaged diff. These commands add no source-whitespace protection at that point. A new historical or whole-tree whitespace audit would be a different check, not something to add implicitly. | -| Fixed credential-pattern scan | Recommend retiring the mandatory release gate; resolve Open Question 4. | The small regex catches some recognizable formats but is incomplete and can match synthetic data. Ordinary credential-aware change review already applies. A broader shared scanner requires its own demonstrated benefit. | -| Exact title plus mandatory Summary, Compatibility, Upgrade, and Changes headings | Adopt ReleaseKit's note convention. | Retain the substantive summary and relevant compatibility/upgrade guidance, but remove the extra structure validator. Section names are an editorial choice. Historical notes remain untouched. | -| Licensing footer and canonical documentation updates | Retain as preparation under the OSS/documentation policies. | ReleaseKit preserves the captured note, including its footer. This does not call for URL probes, a recurring attribution audit, or another publication sign-off. | -| Completed-roadmap retirement | Retain as preparation housekeeping. | Determining whether feature work is complete is project-specific. It does not justify a generic automatic gate or a new human approval step. | -| Separate builds, binary targets, provider probes, CI/module-availability waits | Keep absent from source publication. | PromptKit has no binary deliverables or live inference requirement for releases. ReleaseKit supports source-only publication. Hosted note-page delivery is considered separately below. | +| Full Go suite | Upstream standard suite, once | Validate the committed candidate through the common workflow. | +| Race detector | `validation.go.race: true` | Preserve protection for PromptKit's concurrent execution and capacity management. | +| Full vet | `validation.go.full_vet: true` | Preserve full static analysis while ReleaseKit disables overlapping test-time vet. | +| Go formatting | `validation.go_format: true` | Replace the local formatting loop with upstream committed-source inspection. | +| Offline Markdown links | `validation.markdown: {}` | Replace the local parser with upstream destination and fragment validation. | +| Committed workspace files | `validation.module_distribution.workspace_files: true` | Enforce the established committed-workspace boundary. | +| Filesystem replacements | `validation.module_distribution.local_replacements: true` | Enforce the established local-filesystem dependency boundary. | -The module-file checks should express the selected requirement accurately. -Workspace-file and local-replacement rules can share reusable upstream -mechanics if there is wider demand, but their policy is not universal to Go -applications. Keeping a small local check is preferable to building a broad -configuration framework solely to eliminate a few lines. +Accept the supported upstream behavior and diagnostics for these selections. +In particular, Markdown links outside the checkout use the default +out-of-scope handling; versioned module replacements are permitted. Shared +checks examine the captured committed source, including applicable nested +paths, rather than implementing a second local interpretation. -## Recommended Upstream Work +Leave package-compilation targets, file-size limits, and the exact push-URL +expectation unselected. No concrete additional requirement has been identified +for them. Binary build settings likewise remain absent for this source-only +library. Future needs can be evaluated through the normal policy process. -### Shared Source And Documentation Checks +### PromptKit-Specific Checks -The strongest immediate requests are reusable Go formatting and local -Markdown-link checks, available through the shared tooling rather than merely -through a Go helper that PromptKit must wrap in its own executable. +Retain one focused additional check that executes the maintained preparation, +execution, and observation examples and verifies their semantic results. +Their expected prompt, output, validation, usage, and retry behavior belongs +to PromptKit. -The consumer needs are straightforward: inspect the selected repository's -tracked source, report actionable failures, and perform offline checks without -rewriting files. Markdown checking should cover local paths and supported -heading fragments while excluding external URL availability checks. Let -ReleaseKit establish its supported Markdown conventions; PromptKit need not -preserve its exact regex parser, anchor algorithm, or blanket rejection of -links outside the repository as universal policy. +This check uses the intended module and local Go context and remains offline. +ReleaseKit runs it after shared validation. It does not repeat the full +suite, vet, formatting, Markdown, or module-distribution checks. -Propose the capabilities and rationale upstream, leaving API and internal -implementation design to ReleaseKit. Its routine-release priorities should -guide whether these checks become shared defaults or optional selections. -Either approach can reduce PromptKit-owned code. PromptKit need not prescribe -mandatory checks for every unrelated consumer. +Ordinary development continues to support validation of uncommitted work +through focused tests, formatting, example execution, and change review. +ReleaseKit's committed-candidate operations are release tools, not a new +requirement to commit before ordinary development validation. -### One Standard Suite With Useful Go Validation +### Publication, Release Notes, And Recovery -Race-enabled execution is a credible upstream request for concurrent Go -projects. Full vet within the same standard test operation is another useful -candidate. The desired benefit is one complete suite execution with the -selected analysis, rather than duplicate test runs or custom per-project test -orchestration. +Retain the main-before-tag workflow: prepare and commit the candidate, push +`main` to `origin`, and run one publication command. Adopt ReleaseKit's +standard guards, committed-note capture, annotated tag, and explicit tag +publication. Successful publication completes the source release. -ReleaseKit currently ignores ambient `GOFLAGS`, so setting that variable is -not a supported way to alter its suite. Do not work around the standard by -trying to filter or neutralize its mandatory tests. Request a small supported -capability if these choices remain release requirements. An arbitrary -replacement validation command is unnecessary for PromptKit's use case. +Candidate preparation continues to include completed-roadmap retirement and +ordinary change review under the project policies. These remain preparation +work, with no added publication sign-off or CI wait. -These enhancements are not prerequisites for adopting publication. Their -acceptance affects the final validation selection, as described under Open -Questions. Shared formatting and link checks can also follow initial adoption; -until they are available, retain a transitional local implementation only for -checks selected to continue. +Adopt the upstream note convention: a version-matched committed Markdown note +with a product/version title, a concise summary, and relevant compatibility +or upgrade guidance. Remove enforcement of the four local section names. +Preserve the licensing footer required by the +[OSS policy](../policy/oss.md#discoverability) and link to canonical contracts +where useful. The note itself supplies the annotation; the extra +`Validated commit` annotation line is unnecessary. -### Work Not Recommended For Upstreaming Now +Recovery uses ReleaseKit's reported state and captured publication endpoint. +The maintainer runbook explains failed and uncertain outcomes and links to +the upstream recovery contract. Published tags and historical notes retain +their contents. CI, hosted delivery, and module availability are separate +from successful source publication. -Do not propose PromptKit's four note headings, example output values, -completed-roadmap judgments, or architecture-specific module restrictions as -ReleaseKit defaults. There is also no value in upstreaming the current -clean-candidate diff-whitespace checks. The narrow credential regex is not a -sufficient basis for a shared security-check subsystem. +Hosted note-page delivery remains the decision described at the end of this +roadmap. -## Recommended Adoption Shape +## Changes Needed From The Current Baseline -Use ReleaseKit's pinned native executable as maintainer tooling. A small -`releasekit.json` profile supplies product identity, remote selection where -needed, and additional checks. A thin repository entry point invokes the tool -and preserves its native exit status; direct `go run` publication loses the -distinction between ordinary failure and an uncertain push. +### Replace Local Release Mechanics -This needs no PromptKit runtime import, `buildinfo` integration, or public API -change. Prefer a separately installed pinned tool over adding release -orchestration to the consumer library's dependency graph. Use a released -version and documented preparation rather than a sibling-checkout dependency -or local `replace` directive. +Add the tool declaration and selected dependency to `go.mod`, with applicable +checksum updates, and introduce the small release profile. Replace local +publication mechanics in `scripts/release.sh` with native tool invocation. -PromptKit should own only its product facts, release-note content, substantive -compatibility choices, and focused additional checks. The selected example, -vet, and module checks should use the intended Go toolchain/module context; -dependency preparation precedes their offline execution. Keep generic -publication guards and recovery tests upstream, with a small local integration -check for the actual profile and entry point when adoption is implemented. +Extract the three example assertions into the focused additional check. +Retire the generic `scripts/release-check.sh` implementation rather than +maintaining parallel shared validators solely for development. -Hosted note pages are supported independently of publication. The ReleaseKit -product roadmap favors pages for source-only consumers, but its implemented -`publish` operation does not require delivery configuration or credentials. -Open Question 3 distinguishes adopting that additional channel from adopting -source publication. +Remove local version, candidate, remote, note-heading, tag, formatting, +Markdown, and module-validation implementations that ReleaseKit replaces. +Remove the release-only diff-whitespace checks: on a clean candidate they +have no changes to inspect. Ordinary development keeps useful +`git diff --check` validation. -## Local Changes Needed When Adoption Is Approved +Remove rejection of an ambient active workspace and the blanket vendor-path +check. Adopt ReleaseKit's controlled test context, and use its committed +workspace/local-replacement selections for the established +[repository-independence requirement](../policy/architecture.md#repository-independence). +The current blanket rejection of all replacement directives gives way to +that more precise upstream check. -| Affected material | Proposed change | +The recommended target also retires the mandatory credential regex, +subject to Open Decision 2. Ordinary credential-aware change review remains +part of development. No replacement scanner is required for adoption. + +### Align Policy And Documentation + +Update the affected canonical owners when the implementation lands: + +| File | Required alignment | | --- | --- | -| `scripts/release.sh` | Replace local orchestration with native ReleaseKit invocation. Preserve one publication entry point. | -| `scripts/release-check.sh` | Remove shared-suite execution and retired gates. Move the retained example assertions and module checks into focused additional checks; use upstream generic checks when available. Decide whether a standalone development command still provides value. | -| `releasekit.json` and tool preparation guidance | Introduce a small profile and a selected released tool version. Build/delivery settings depend on the chosen deliverables. | -| `docs/policy/release.md` | Adopt shared validation, note structure, and recovery behavior; preserve source/tag integrity, compatibility policy, catalog exceptions, and the no-CI-wait completion rule. Record any selected delivery channel. | -| `docs/policy/testing.md` | Update the release-candidate validation description consistently with the selected race/vet approach and retained consumer workflows. | -| `docs/release.md` | Document preparation, the single publication command, ReleaseKit failure states, and recovery. Link to upstream contracts rather than recreating them. | -| `docs/development.md` | Replace the current script inventory and prerequisites with the implemented tool/check ownership and proportionate development validation. | -| `docs/policy/architecture.md` | Preserve the explicit committed-workspace/local-replacement boundary. Only adjust text if adoption actually changes that deliberate project decision. | -| Release notes and licensing material | Describe adopted operational changes in the next appropriate release note. Preserve the OSS footer. Tool use alone requires no new attribution entry; assess any copied/adapted implementation or documentation under the [OSS policy](../policy/oss.md). | +| `docs/policy/release.md` | Describe the shared validation selections, simpler note convention, adopted publication/recovery model, retired gates, and selected deliverables. Preserve existing compatibility and catalog-profile policy. | +| `docs/policy/testing.md` | Route release validation through ReleaseKit while retaining race, full vet, and the three consumer workflows. Distinguish ordinary development checks from committed-candidate validation. | +| `docs/release.md` | Provide the short executable runbook for tool/dependency preparation, candidate preparation, one publication command, and upstream recovery. | +| `docs/development.md` | Replace the old checker inventory and prerequisites with current tool ownership and focused development commands. | +| `docs/oss/attribution.md` and related notices, if applicable | Apply the OSS policy to the selected tooling and any copied or adapted material according to actual use and distribution. Tool use alone is not a blanket attribution requirement. | -These are proposed changes, not permission to update unrelated policies or -distribution channels during this assessment. A later implementation plan -should use the selected released upstream contracts and resolved decisions. +Repair affected incoming links as old scripts are retired. Keep exact upstream +CLI/profile contracts in their upstream owners and PromptKit's selected +release policy in its own canonical documents. The architecture policy's +existing committed-workspace and local-replacement rule remains the relevant +local requirement. -## Expected Benefit And Validation +When preparing the eventual PromptKit release, describe the operational +migration in its release note. This roadmap does not itself select or publish +that version or retrofit past release records. -The immediate benefit is eliminating most of the 57-line publication script -and moving its consequential Git behavior and recovery maintenance upstream. -Most of the remaining 152 lines are validation, including a large generic -Markdown checker. Shared checks, removal of ineffective gates, and simpler -note rules can remove substantially more. Exact savings depend on upstream -capabilities and the selected validation policy; no deletion quota is needed. +## Verification And Completion -The resulting local surface should be a tool invocation, product settings, -and small project-specific checks. Validate those through a representative -offline integration using a temporary Git remote, not by reimplementing or -retesting ReleaseKit's entire publication matrix. Generic checks receive their -behavioral coverage upstream; local tests cover meaningful wiring and -PromptKit-specific expectations. Live hosted delivery validation is relevant -only if that channel is selected, and never delays source-release completion. +The implementation should demonstrate that PromptKit's profile and entry point +select the released tool and expected checks, that the maintained examples +still verify meaningful consumer behavior, and that the resulting procedure +can validate and publish to a temporary Git remote. -## Open Questions +Use a small representative integration fixture for local wiring and failure +propagation. ReleaseKit owns the shared validators' and publication machinery's +detailed behavioral tests. Avoid duplicating its matrix or recursively running +PromptKit's complete suite from an integration test. -### 1. Should Race Detection Remain A Release-Candidate Gate? +Adoption is complete when the implemented release path uses ReleaseKit, +the selected shared validators replace local equivalents, the retained +example check is integrated, and policies and runbooks describe the actual +workflow. Source-publication testing requires no provider credentials or +live inference. If hosted delivery is selected, its integration has its own +verification and delivery status. -**Recommendation:** Seek supported upstream race-enabled standard-suite -execution and select it for PromptKit if accepted. Concurrency is substantive -library behavior, so this protects a real failure class while retaining one -suite run. This is a capability request, not a requirement to preserve our -exact existing shell command or to enable race testing for every consumer. +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. -**Alternative:** Adopt the current ordinary ReleaseKit suite and use race -testing during concurrency-related development. This provides immediate -standardization and avoids an upstream option or additional release cost, but -removes a last check for races introduced outside explicitly concurrency-focused -work. If the upstream capability is unavailable, this is the recommended -fallback after deliberately updating the release/testing policies; do not -block adoption indefinitely or silently run the complete suite twice. +## Open Decisions -### 2. How Much Static Analysis Should Publication Require? - -**Recommendation:** Keep full vet through a configured `go vet ./...` check -initially, and ask ReleaseKit to consider full vet as part of its one standard -test operation. Current `go test` includes only a subset of analyses, so full -vet can catch additional defects. The transitional command costs virtually -no local implementation, though it repeats some analysis. - -**Alternative:** Use only ReleaseKit's standard `go test` vet subset and run -full vet during ordinary development. This most closely follows the minimal -upstream baseline and removes overlapping analysis; it trades away release-time -coverage of the omitted analyses. Either choice requires updating the existing -explicit static-analysis requirement rather than assuming the checks are -equivalent. - -### 3. Should Adoption Add Hosted Gitea Release Notes? +### 1. Include Hosted Gitea Release Notes In This Adoption? **Recommendation:** Adopt source publication first and leave hosted delivery -for a separately selected expansion. Source publication already provides the -desired standardization. PromptKit currently has no hosted CI, and adding a -delivery workflow and credentials is additional operational scope rather than -a prerequisite for using ReleaseKit. +for a separately selected expansion. This achieves the immediate +standardization and maintenance goals. PromptKit currently has no hosted CI; +introducing a runner workflow and delivery credentials adds operational +scope rather than enabling the shared validation features. -**Alternative:** Include asynchronous page-only delivery in adoption, using -the upstream maintained workflow and the committed note as the hosted body. -This follows ReleaseKit's broader consumer direction and improves release -discoverability with little bespoke code. It requires provisioning CI and a -Gitea credential, plus keeping delivery status and retries separate from source -publication. Successful tag publication still completes the release, even -when page delivery is delayed or fails. +**Alternative:** Include asynchronous page-only delivery using ReleaseKit's +maintained module-selected Woodpecker integration. This follows upstream's +broader consumer direction and improves release discoverability with little +bespoke implementation. It requires a delivery profile, CI configuration, +credentials, and documented delivery retries. The released tag selects the +tool for retries, and successful source publication still completes the +release independently of page delivery. -### 4. Is The Credential-Pattern Scan Worth Retaining As A Gate? +### 2. Retire Or Retain The Credential-Pattern Gate? -**Recommendation:** Retire the mandatory release scan and retain the existing -credential-aware ordinary change review. The regex offers narrow detection -and can reject synthetic fixtures; there is no evidence in this assessment -that it provides enough additional protection to warrant preserving it as a -shared release requirement. This changes the selected check, not the obligation -to keep actual credentials out of committed source. +**Recommendation:** Retire the mandatory regex scan and retain ordinary +credential-aware change review. Its limited formats and possible matches +against synthetic fixtures do not justify preserving a separate local gate +merely because ReleaseKit has no equivalent. This simplifies publication +without changing the obligation to keep actual credentials out of source. -**Alternative:** Keep the small check, or request an optional shared equivalent, -if catching a few recognizable accidentally committed credential formats is -worth its low execution cost and possible false positives. This provides an -independent automated signal beyond review. Its supported formats and intended -scope should remain explicit, without treating it as comprehensive detection -or making a broader scanner a prerequisite for adoption. +**Alternative:** Retain the small existing scan as a focused additional +check if its independent automated signal is considered worth its cost and +false positives. This catches some recognizable accidentally committed +formats but leaves a local validation fragment to maintain and is not +comprehensive detection. It does not require a new upstream security +subsystem.