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`. A successful push
of the selected annotated tag, after its source commit is available on `main`,
completes the release. Do not wait for CI or Go module availability.
After source publication, deliver the hosted Gitea release page as described
below. Report source publication and hosted delivery separately.

## 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, the
candidate validation, and the maintained examples. Make it the active `go`
command and record its version:

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

For a minor release, advance Promptkit's consumer minimum to the initial stable
release of that Go series before committing the candidate:

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

For example, Go 1.27.1 normally results in `go 1.27.0`. Keep a higher patch
minimum if a dependency or identified correctness fix requires it. For a patch
release, leave the consumer minimum unchanged; using a newer validation
toolchain does not itself raise that minimum. If the candidate needs a higher
minimum, prepare a minor release instead. See the
[consumer-minimum policy](policy/release.md#consumer-minimum-and-release-toolchain).

Prepare module caches before validation; this may update `go.sum` and belongs
before the candidate commit:

```sh
GOTOOLCHAIN=local 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
relevant compatibility impact or upgrade instructions. No fixed section
headings are required. Describe a raised Go minimum and its compatibility
impact under the [versioning policy](policy/release.md#versioning-and-compatibility).
End each new note with the licensing footer below, using the selected version:

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

Check the footer paths against the candidate; the future tag need not resolve
remotely during preparation. Follow the [OSS policy](policy/oss.md) for these
links. Hosted delivery reuses this complete note without a separate summary.
Promptkit publishes no binaries, attachments, or checksum manifests.

For hosted delivery, supply a Gitea API token with access to publish releases
through `RELEASEKIT_GITEA_TOKEN` or the ignored local file
`.releasekit/gitea-token`, with owner-only permissions for the file. A nonblank
environment value takes precedence. ReleaseKit trims surrounding whitespace
from file contents. Keep the token out of commits and shared logs. The profile
rejects that exact token path if
committed; it does not scan other files or Git history. Source publication uses
Git authentication and neither reads nor requires the delivery token.

Retire completed roadmaps while preserving deferred work and repairing incoming
links. Review the intended changes through the ordinary development workflow,
commit the candidate on `main`, and push `main` to `origin` before publication.
Preparation may update module metadata; the release bootstrap and validation
preserve the committed candidate.

## Validate And Publish

For an optional local diagnostic of a committed candidate, run:

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

This is not a required step before publication. The upstream
[candidate-check contract](https://forge.maximumdirect.net/base-layer/releasekit/src/tag/v0.7.0/docs/consumers/check.md)
describes its requirements.

Run the single publication command with the chosen version:

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

The familiar wrapper delegates to the native ReleaseKit executable selected in
`go.mod`. The committed [profile](../releasekit.json) selects the race-enabled
Go suite, full vet, committed Go formatting, local Markdown links, workspace
and filesystem replacement inspection, and semantic checks for the three
maintained offline consumer examples. It also checks that the configured local
token path is not committed. ReleaseKit verifies the committed
candidate and publication state, then publishes only the selected tag. Its
checks run once for this candidate; do not repeat them as a separate sign-off.

The native command returns status 0 for confirmed publication, 1 for a known
validation or publication failure, 2 for invalid input or profile, and 3 when
the push outcome remains unknown. Successful publication needs no remote
read-back, CI wait, or installation check. Provider probes and inference calls
are not part of validation.

## Deliver The Hosted Release

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

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

The profile selects Gitea at `https://forge.maximumdirect.net`, owner
`base-layer`, repository `promptkit`. With no build targets, ReleaseKit creates
or accepts a stable, non-draft release page containing the complete committed
note and licensing footer. There is no binary build, attachment upload, or
candidate revalidation. Delivery does not publish another tag or wait for CI.

ReleaseKit performs its authenticated, read-only repository preflight during
delivery; no separate preflight is required before source publication. Missing
credentials or an unavailable hosted service leave the source release complete.

Delivery returns status 0 for completion, 1 for an operational failure,
conflict, or partial delivery, 2 for invalid configuration or credential/access
errors, and 3 for an unresolved hosted write. Report the hosted URL on success
and retain the diagnostic and delivery state on failure. See the upstream
[delivery guide](https://forge.maximumdirect.net/base-layer/releasekit/src/tag/v0.7.0/docs/consumers/delivery.md)
for the full result contract.

For a later retry, use a clean checkout of the original tag with its recorded
module files and make the token available locally. For example, in a separate
checkout with the tag available:

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

The launcher builds the tool selected by that checkout. Matching hosted content
is accepted; conflicting content is not overwritten. Resolve an unknown hosted
write before retrying. Retry delivery with the same immutable version rather
than rerunning `publish` or moving a tag. Corrections to published source or
content require a new appropriate version. These steps apply to tags containing
this delivery configuration; older releases retain their original workflows.

## Failure Recovery

This section covers source publication. Hosted-delivery recovery is described
[above](#deliver-the-hosted-release); its failure does not undo source publication.

For status 1, use the diagnostic to distinguish a validation failure from a
known publication conflict. Correct and commit candidate defects, push `main`,
and rerun publication with an unused version when appropriate. Status 2 means
the invocation or profile must be corrected.

If local tag creation or verification fails, inspect the reported local ref:
it may remain even when ReleaseKit could not establish its object ID. Apply
the authoritative-state checks below before removing a retained tag.

For status 3, do not retry or remove the local tag until the remote outcome is
resolved. ReleaseKit reports the attempted version, tag object, and recovery
state, including the captured publication endpoint when available. Use that
endpoint—not merely the current `origin` URL—to query the exact tag; follow the
upstream
[failure-recovery procedure](https://forge.maximumdirect.net/base-layer/releasekit/src/tag/v0.7.0/docs/release.md#resolve-failures).

CLI diagnostics mask HTTP(S) credentials. If the displayed endpoint is
redacted, use the actual endpoint captured for that attempt, with authentication
supplied locally; do not copy the redacted display as a transport URL or expose
credentials in shared logs.

```sh
releasekit_endpoint='COPY_CAPTURED_ENDPOINT'
releasekit_version='vX.Y.Z'
test "$(git ls-remote --get-url -- "$releasekit_endpoint")" = "$releasekit_endpoint" &&
  git ls-remote --refs -- "$releasekit_endpoint" "refs/tags/$releasekit_version"
```

Compare the returned object ID with the reported tag object. An exact match
confirms publication. A missing ref confirms absence only when the endpoint
identity check and query both succeed. If either check fails, the outcome
remains unknown; correct the transport configuration and resolve it before
retrying. Only after authoritative absence is confirmed may an unpublished
local tag be removed before correcting the candidate or retrying. Never move,
overwrite, or delete a published tag.

## Policy Changes

Update the policy and this procedure together when changing release governance.
Consumers own their dependency-availability and release checks; their readiness
does not delay completion of a Promptkit release.