promptkit/docs/roadmap/releasekit.md

# ReleaseKit Adoption Roadmap

Status: Adoption scope for review; implementation has not started.
A companion staged implementation plan will define the implementation steps.

## Purpose

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

## Baseline And Available Upstream Support

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.

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.

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 upstream owners of the adopted behavior are:

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

No further upstream feature work is needed for the proposed source-publication
scope.

## Target End State

### Tool Selection And Local Ownership

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.

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

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.

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.

### PromptKit-Specific Checks

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.

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.

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.

### Publication, Release Notes, And Recovery

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.

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.

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.

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.

Hosted note-page delivery remains the decision described at the end of this
roadmap.

## Changes Needed From The Current Baseline

### Replace Local Release Mechanics

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.

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.

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.

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.

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

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.

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.

## Verification And 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.

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.

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.

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.

## Open Decisions

### 1. Include Hosted Gitea Release Notes In This Adoption?

**Recommendation:** Adopt source publication first and leave hosted delivery
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 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.

### 2. Retire Or Retain The Credential-Pattern Gate?

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