Align repository policies with shared standards

docs/policy/release.md

@@ -0,0 +1,221 @@
+# Release Policy
+
+**Base Policy Version:** 1.0
+
+**Last Updated**: 2026-09-25
+
+## Purpose
+
+This policy defines the minimum requirements for selecting, validating,
+publishing, verifying, and correcting releases. Its goal is to make every
+release intentional, reproducible from an exact source revision, documented
+for consumers, and safe from retrospective replacement.
+
+The repository-specific commands that implement these requirements belong in
+`docs/release.md`. Historical release summaries belong in `docs/releases/`.
+Neither document may weaken this policy, including its explicit repository
+exceptions.
+
+## Release Model
+
+A release consists of:
+
+- one exact source commit reachable from the repository's primary branch;
+- one immutable version tag identifying that commit;
+- one version-matched, checked-in release note; and
+- every artifact, image, package, registry entry, or other deliverable the
+  repository declares for that release.
+
+The repository's primary branch is `main` unless an adopted policy documents
+an exception. A release candidate must be committed and pushed to that branch
+before its release tag is published.
+
+The source tag is the authoritative release identity. Published deliverables
+must be traceable to the tagged source and must agree with its version. A
+repository may publish source only. When it publishes additional deliverables,
+its release procedure must enumerate them and define how each is built,
+identified, published, and verified.
+
+Release automation may validate or publish a release only when its exact
+responsibility is documented. Automation must not silently change the source
+candidate, move a published tag, replace a published deliverable, or repair a
+release in place.
+
+## Versioning And Compatibility
+
+Stable releases use Semantic Versioning in the form `vMAJOR.MINOR.PATCH`, with
+no leading zeroes. Each version must be unused locally and in every configured
+remote or publication channel before publication begins.
+
+Unless an adopted policy explicitly supports and defines prereleases,
+prerelease versions are not permitted.
+
+For releases at or after `v1.0.0`:
+
+- a major release may make intentional incompatible changes;
+- a minor release may add backward-compatible behavior; and
+- a patch release may make backward-compatible fixes.
+
+Before `v1.0.0`, a minor release may change a documented public, operational,
+configuration, data, integration, or compatibility contract when the release
+note explains the impact and required consumer action. A patch release must
+not intentionally break those contracts within its minor line.
+
+A repository with additional compatibility promises must define them in its
+adopted policy or canonical contract documentation. A release note may explain
+a compatibility change, but it must not redefine the current compatibility
+contract.
+
+## Release Documentation
+
+Every release made under this policy must include
+`docs/releases/<version>.md` in the tagged source tree. The filename must use
+the complete version tag, and the document must begin with a title containing
+the product name and that exact version.
+
+Every new release note must contain these sections:
+
+```markdown
+# <Product> vMAJOR.MINOR.PATCH
+
+This release ...
+
+## Summary
+
+## Compatibility
+
+## Upgrade
+
+## Changes
+```
+
+Use an explicit statement such as "No action required" when a section has no
+substantive content.
+
+Release notes are immutable historical summaries. They should link to current
+canonical documentation for exact behavior. Every affected canonical document
+must be updated in the same candidate; a release note must not substitute for
+current documentation or defer required documentation changes.
+
+## Candidate Preparation And Validation
+
+Each repository must provide one documented release-check command or script
+that exercises the complete set of automated source-candidate gates. The
+repository-specific procedure must state all additional manual gates.
+
+The required gates are:
+
+- dependency or module hygiene appropriate to the language and ecosystem;
+- the complete deterministic, offline default test suite;
+- static analysis and linting used by the repository;
+- formatting and whitespace checks;
+- validation of maintained examples, configuration, schemas, generated
+  sources, and documentation commands where applicable;
+- review of changed local documentation links;
+- removal of obsolete roadmap documents under `docs/roadmap/` that describe
+  completed work included in the release; and
+- review for unintended files, generated output, credentials, private data,
+  and unrelated changes.
+
+## Publication Guards
+
+Immediately before publication, the maintainer or release automation must
+fetch the current primary branch and tags from the authoritative remote and
+verify all of the following:
+
+- the version has the required format and is not already published;
+- the current branch is the primary release branch;
+- the worktree and index are clean;
+- the current commit is the recorded, validated candidate;
+- the authoritative remote branch points to that same commit;
+- the matching release note exists in that commit and has the required title
+  and sections;
+- all required approvals and automated gates succeeded for that commit; and
+- no local or remote tag already uses the selected version.
+
+Create the version tag against the guarded commit and verify its target before
+publishing it. Publish only the exact intended ref and deliverables. Broad
+operations such as `git push --tags` are discouraged because they can publish
+unreviewed refs unrelated to the release.
+
+The repository-specific procedure must make these guards executable or give
+copyable commands for performing them.
+
+## Immutability And Correction
+
+Published version tags and published deliverables are immutable. Do not move,
+overwrite, recreate, or delete a published tag. Do not replace an artifact,
+image, package, checksum, signature, provenance statement, or release note
+under an already published version.
+
+If validation fails before publication, correct the candidate, rerun the
+complete gates, and repeat the publication guards. An unpublished local tag
+may be removed after confirming that it was never published or used by a
+release channel.
+
+If publication or post-publication verification reveals a defect, leave the
+published release intact. Correct the defect on the primary branch, choose a
+new patch version or other semantically appropriate new version, write a new
+matching release note, and perform the complete release procedure again.
+
+A distribution channel's supported yank, deprecation, or advisory mechanism
+may warn consumers away from a defective release, but it must not replace that
+release's contents or reuse its version.
+
+## Repository Release Procedure
+
+Every adopting repository must maintain `docs/release.md` as the canonical
+maintainer runbook for implementing this policy. It must define, in execution
+order:
+
+1. maintainer prerequisites and required access;
+2. version selection and compatibility review;
+3. release-note creation;
+4. candidate preparation and the complete validation command;
+5. candidate commit, push, and exact commit recording;
+6. publication guards;
+7. exact tag and deliverable publication commands;
+8. authoritative remote and consumer-facing verification; and
+9. failure handling and correction.
+
+The procedure should use copyable, fail-fast commands where practical. It must
+name the primary branch, authoritative remote, tag form, published
+deliverables, supported build targets, release automation responsibilities,
+and consumer verification path. It must link to this policy instead of
+restating or redefining its requirements.
+
+## Policy Exceptions
+
+### Tag-push completion and asynchronous deliverables
+
+Narratio's automated release responsibility ends when the exact intended tag is
+successfully pushed to `origin`. It must not wait for, poll, or check CI/Gitea
+results, download assets, or verify their checksums as a completion condition.
+Binary and checksum publication is asynchronous; consumer-facing inspection is
+optional follow-up, not a gate on the source release.
+
+This deliberately qualifies the base policy's complete-deliverable and
+post-publication verification requirements. CI reliability is outside the
+release command's scope; an unavailable publication service must not cause an
+automated releaser to wait indefinitely or claim to repair a published version.
+
+Compensating controls are complete local candidate validation (including supported
+cross-builds and a host version check), exact source/tag guards, immutable source
+tags, asynchronous build validation, and non-overwriting asset publication.
+Successful tag publication is not evidence that binary assets are available.
+Optional inspection and corrective-release procedures belong in
+[the release procedure](../release.md).
+
+### Authoritative publication scope
+
+Narratio's synchronous publication guards inspect the authoritative `origin`
+remote and its `main` branch, not every configured Git remote or a Gitea release
+entry. The command does not add release-service or registry availability checks.
+This qualifies the base policy's all-channel unused-version requirement.
+
+Other remotes are not Narratio release authorities, and Gitea asset publication
+is asynchronous. The compensating controls are local and origin tag uniqueness,
+exact candidate matching, and the publisher's non-overwrite settings. Any known
+already-published version or conflicting deliverable remains ineligible for
+reuse: choose a new version rather than bypassing guards. A future additional
+distribution channel requires deliberate policy/procedure updates.