promptkit/docs/release.md

# Release Procedure

This runbook implements the [release policy](policy/release.md). Promptkit
publishes source-only Go module tags from `main` to `origin`, followed by a
page-only Gitea release. Successful publication of the intended tag, with its
source commit available on `main`, completes the source release. Report hosted
delivery separately. Do not wait for CI or Go module availability.

## Prepare The Candidate

Required tools are Git, Go with race-detector support, POSIX shell, and Python
3. Work from the repository root with push access to `origin`.

Use the latest Go installation available locally for the release tool and its
child commands. Put it first on `PATH` and keep it selected throughout:

```sh
export GOTOOLCHAIN=local
go version
```

For a minor release, normally advance the consumer minimum to the initial
stable patch of that Go series:

```sh
release_go_version=$(go env GOVERSION)
release_go_series=${release_go_version#go}
release_go_series=${release_go_series%.*}
go mod edit "-go=${release_go_series}.0"
```

Retain a higher patch minimum when required by a dependency or identified fix.
For a patch release, preserve the existing minimum. Explain minimum increases
under the [versioning policy](policy/release.md#versioning-and-compatibility).
Prepare dependency caches before committing the candidate:

```sh
go mod download
```

Choose an unused stable version and create `docs/releases/<version>.md` with a
title containing `Promptkit` and that exact version, a short summary, and any
compatibility impact or upgrade instructions. End the note with:

```markdown
[COPYRIGHT](https://forge.maximumdirect.net/base-layer/promptkit/src/tag/vX.Y.Z/COPYRIGHT) | [LICENSE](https://forge.maximumdirect.net/base-layer/promptkit/src/tag/vX.Y.Z/LICENSE) | [ATTRIBUTION](https://forge.maximumdirect.net/base-layer/promptkit/src/tag/vX.Y.Z/docs/oss/attribution.md)
```

Substitute the selected version and check the paths against the candidate;
future tag URLs need not resolve during preparation. Follow the
[OSS policy](policy/oss.md). Historical notes and tags remain unchanged.

Supply delivery credentials through `RELEASEKIT_GITEA_TOKEN` or the ignored
local file `.releasekit/gitea-token`, with owner-only file permissions. A
nonblank environment value takes precedence. Source publication neither reads
nor requires this token. The [profile](../releasekit.json) selects the token
path for committed-file protection; keep credentials out of commits and logs.

Retire completed roadmaps, preserve unfinished work, and repair affected links.
Review and commit the candidate on `main`, including any module updates, then
push `main` to `origin` before publishing its tag.

## Validate And Publish

```sh
./scripts/release.sh vMAJOR.MINOR.PATCH
```

The launcher uses `go tool` to build or reuse the module-selected ReleaseKit
executable in Go's cache, using the selected local toolchain. ReleaseKit runs
the [profile's checks](../releasekit.json) once, verifies publication state, and
publishes only the intended tag. Preserve its native exit status and diagnostic.
Successful publication needs no separate remote read-back or CI wait.

For optional local diagnosis, use `./scripts/releasekit.sh check VERSION`.
It is not a required step before publication. The upstream
[candidate-check guide](https://forge.maximumdirect.net/base-layer/releasekit/src/tag/v0.8.0/docs/consumers/check.md)
and [CLI contract](https://forge.maximumdirect.net/base-layer/releasekit/src/tag/v0.8.0/docs/cli.md)
own shared checks and exit-status definitions.

## Deliver The Hosted Release

After source publication, keep a clean checkout at the published tag's commit:

```sh
./scripts/releasekit.sh deliver vMAJOR.MINOR.PATCH
```

The profile selects page-only Gitea delivery for this repository. The hosted
body is the complete checked-in note, including its licensing footer. There are
no binary assets, checksum manifests, candidate revalidation, or CI waits.
ReleaseKit checks delivery credentials during delivery, not as a publication
gate. Report the hosted URL on success; delivery failure leaves the source
release complete.

For a later retry, use a clean checkout of the original tag with its recorded
module files and supply the token there. In a separate checkout, for example:

```sh
git switch --detach vMAJOR.MINOR.PATCH
./scripts/releasekit.sh deliver vMAJOR.MINOR.PATCH
```

Resolve uncertain hosted writes before retrying the same immutable version.
Matching content is accepted; conflicts are not overwritten. Do not rerun
`publish` or move tags to repair delivery. Follow the upstream
[delivery guide](https://forge.maximumdirect.net/base-layer/releasekit/src/tag/v0.8.0/docs/consumers/delivery.md)
for result interpretation and recovery. These commands apply to tags containing
this delivery configuration; older releases retain their original workflows.

## Failure Recovery

For source-publication failures, use ReleaseKit's status and diagnostic to
distinguish a candidate defect from a publication conflict. Correct and commit
candidate defects, push `main`, and rerun publication as appropriate. A failure
after local tag creation may leave a ref even when its object ID is unavailable.

Status 3 means the push outcome remains unknown. Do not retry or remove the local
tag until the authoritative outcome is resolved. ReleaseKit attempts to save
private publication evidence and reports a record path or a separate recording
warning. A recording failure does not change the publication outcome.

Use the recovery command reported for that attempt, or discover local records
and explicitly select the matching attempt:

```sh
./scripts/releasekit.sh publication-attempts
./scripts/releasekit.sh reconcile --record /absolute/path/to/selected-record.json
```

Discovery is local; reconciliation observes the original destination without
rerunning validation, changing tags, or delivering hosted content. Neither is
a routine gate after successful publication. Follow the upstream
[recovery procedure](https://forge.maximumdirect.net/base-layer/releasekit/src/tag/v0.8.0/docs/release.md#resolve-publication-failures)
for outcomes, incomplete evidence, and older attempts without records.

Records are stored under Git's common directory by default and can contain
credential-bearing endpoints. Keep them private, out of source control and
shared logs; retain them while needed for recovery and remove them when that
value expires. See the [evidence guide](https://forge.maximumdirect.net/base-layer/releasekit/src/tag/v0.8.0/docs/consumers/publish.md#retain-and-reconcile-publication-evidence)
for storage and retention details.

Current absence does not prove a version was never published. Remove a retained
local tag only after establishing absence and confirming it was not already
published or used by another release channel. Never reuse a known published
version or replace a published tag or hosted page. Corrections require a new
appropriate version.