Align project policies and simplify the release workflow

docs/policy/release.md

@@ -0,0 +1,146 @@
+# Release Policy
+
+**Base Policy Version:** 1.0
+
+**Last Updated:** 2026-09-23
+
+## Purpose And Adoption Scope
+
+This policy owns Promptkit's release requirements and compatibility rules.
+The [release procedure](../release.md) owns the commands used to satisfy them.
+This scoped adoption applies to releases prepared after its adoption on
+2026-09-23. Published tags and historical notes are not rewritten to retrofit
+the new note format.
+
+## Release Model And Compatibility
+
+Promptkit publishes source-only Go module releases from committed, pushed
+`main` candidates through annotated `vMAJOR.MINOR.PATCH` tags. It publishes
+no binaries, hosted releases, or other artifacts and uses maintainer-run
+validation rather than hosted CI. Versions must be unused locally and on
+`origin`; the existing procedure accepts stable version tags only.
+
+Before v1, minor releases may change the public API and patches preserve
+compatibility within their minor line, subject to the catalog-data provision
+below. Release notes must identify compatibility impact, public API changes,
+and required consumer action. The source tag identifies the exact release;
+the checked-in note at that tag records its historical summary.
+
+## Catalog Profile Compatibility
+
+External catalog profile data may be added, removed, renamed, or modified
+without deprecation or advance notice. This exception is limited to profile
+data imported from the maintained catalog modules. It does not weaken ordinary
+compatibility for Promptkit's public Go API, configuration and format semantics,
+runtime behavior, catalog-module APIs, manifest schema, backend definitions, or
+consumer-owned definitions.
+
+Within the catalog versions selected and tested by a Promptkit release, and
+unless a consumer overrides the name or its base, Promptkit keeps the literal
+profile IDs `promptkit-openrouter-standard` and
+`promptkit-openrouter-auto` available. The names do not promise a permanent
+model, backend, routing behavior, settings, cost, output, or upstream
+availability. The [framework format reference](../formats.md#built-in-profile-catalog)
+owns their current definitions.
+
+`v0.10.0` is the initial minor release for this compatibility transition.
+Afterward, catalog-only updates and adjustments to the current selections may
+ship in a patch release when all other compatibility obligations remain intact.
+External profile removals can require consumer action; they are not automatic
+migrations.
+
+Catalog adoption and release validation remain local and offline. They do not
+probe provider endpoints, request model lists, or make inference calls.
+
+## Release Documentation
+
+Every new release must include `docs/releases/<version>.md` in the tagged
+source, using the complete tag as the filename. Its title contains Promptkit
+and that exact version. Use this structure:
+
+```markdown
+# Promptkit vMAJOR.MINOR.PATCH
+
+This release ...
+
+## Summary
+
+## Compatibility
+
+## Upgrade
+
+## Changes
+```
+
+State “No action required” or “None” where appropriate rather than omitting a
+section. Keep exact current contracts in their canonical documents and link
+to them. Update affected canonical documentation in the same candidate.
+
+These notes are historical records, not optional disposable guidance. Published
+release-note contents must not be replaced under the same version. Corrections
+belong in a subsequent release. Annotated-tag messages complement the checked-in
+note: generate the annotation from that note and the validated commit rather
+than maintaining a second summary.
+
+## Validation And Publication
+
+The [publication script](../../scripts/release.sh) runs the
+[local checks](../../scripts/release-check.sh) once for the final candidate.
+Retain clean-candidate, synchronized-main, unused-version, module-hygiene,
+release-note structure, and tag-target checks. Publish only the selected tag
+ref. Changing the candidate requires fresh validation. No provider endpoint
+probes or inference calls are release checks.
+
+Release-note content and retirement of completed roadmaps are preparation
+responsibilities, not separate human sign-off gates. Preserve planned and
+deferred work and repair links. Ordinary change review covers unintended files,
+secrets, and private data; do not repeat it as a release-specific approval.
+
+A successful tag push to origin completes the release. Never wait for CI to
+finish or succeed. CI results, remote read-back, and Go module availability
+are informational follow-ups, not completion gates. An ambiguous push result
+requires confirming publication on origin, not waiting for CI.
+
+## Immutability And Failure Recovery
+
+Never move, replace, recreate, or delete a published tag or replace published
+release contents. If validation fails before publication, correct the candidate,
+rerun the complete checks, and repeat the publication guards. Remove an
+unpublished local tag only after confirming it was not published.
+
+If publication or subsequent investigation reveals a defect, leave the
+published release intact. Correct the defect on main, select a new patch or
+other semantically appropriate version, write its matching release note, and
+repeat the complete procedure. If publication status is uncertain, inspect
+the authoritative remote before deciding whether a tag is unpublished; do not
+overwrite it to retry.
+
+Transient network, authentication, CI, or module-availability failures do not
+by themselves warrant a new version. Investigate separately and publish a
+corrective release only when published contents actually need changing.
+
+## Policy Exceptions And Deliberate Scope
+
+This adoption follows the maintainer-approved lean workflow rather than every
+base-policy guard:
+
+- Collision checks concern origin, the authoritative publication destination,
+  rather than every configured remote. Local and origin tag checks, synchronized
+  main, and an explicit selected-ref push protect the actual release channel.
+- Automated local validation and publication-state checks replace manual
+  mechanical inspections and separate human sign-offs. Ordinary change review,
+  editorial responsibility for release notes, and roadmap housekeeping remain;
+  repeating them as approvals would add friction without distinct protection.
+- Successful tag publication completes this source-only release. CI can be slow
+  or unreliable, and module availability depends on external services. Neither
+  is a completion gate. Local candidate validation and explicit tag-target
+  checks protect publication; ambiguous push results are resolved against origin.
+  Actual defects are corrected in a new release, never by replacing a tag.
+
+Ignored local files are not prohibited merely because they exist: they are not
+included in the tagged commit. The clean-candidate guard and ordinary review of
+tracked changes protect the published contents.
+
+The catalog profile provision preserves an already approved compatibility
+boundary; it does not extend volatility to backend definitions or runtime
+contracts. Further release-governance changes require deliberate approval.