Simplify source releases with one guarded publication command

docs/policy/architecture.md

@@ -357,8 +357,9 @@ best-effort development and compilation environment, while Windows is
 unsupported. Notarius distributes source releases only: an immutable source
 tag and its checked-in release note identify a release. The project does not
 publish executable binaries, archives, installers, container images,
-checksums, signatures, or package-manager entries. Maintainer release commands
-and tag guards belong to [Source Releases](../release.md).
+checksums, signatures, or package-manager entries. [Release Policy](release.md)
+owns publication requirements and completion; maintainer commands and guards
+belong to [Source Releases](../release.md).
 
 ## Architectural Non-Goals
 

docs/policy/documentation.md

@@ -91,7 +91,8 @@ secret values.
 | CLI contract | `docs/cli.md` | Commands, arguments, flags, invocation semantics, and exit codes. | End-to-end operating procedures, configuration field definitions, runtime filesystem layout, module implementation details. |
 | Configuration contract | `docs/config.md` | Discovery and precedence, file schema, fields, defaults, environment overrides, validation rules, and user-selectable module or validator keys. | Complete example files, CLI syntax, runtime state lifecycle, module implementation details. |
 | Operations | `docs/operations.md` | Runtime workflows, physical filesystem and state layout, output, cache, and debug handling, resume, cleanup, permissions, recovery, and operational limits. | CLI flag syntax, configuration field definitions, logical output schemas, implementation mechanics. |
-| Source release procedure | `docs/release.md` | Maintainer release selection, candidate validation, tagging, publication guards, verification, and immutable-tag recovery. | Product installation summary, CLI version semantics, historical release summaries, CI implementation detail. |
+| Release policy | `docs/policy/release.md` | Versioning, compatibility, integrity, immutability, proportionate gate selection, publication controls, and release completion. | Concrete commands, product installation, historical notes, and CI implementation detail. |
+| Repository-specific release procedure | `docs/release.md` | Prerequisites, candidate preparation, publication command, automated guards, optional diagnostics, and failure recovery. | General release requirements, product installation guidance, historical summaries, and current compatibility contracts. |
 | Release-note history | `docs/releases/` | One checked-in historical summary for each source release made under the procedure. The note at the immutable tag is that release's record. | Current commands, behavior, contracts, and compatibility definitions. |
 | Public HTTP contract, if introduced | `docs/api.md` | Routes, authentication, media types, request and response schemas, status codes, pagination, caching, idempotency, rate limits, and HTTP retry semantics. | Client walkthroughs, upstream or downstream integration internals, implementation detail. |
 | Consumer guidance | `docs/consumers/` | Task-oriented subprocess use, minimal client examples, consumer responsibilities, and guidance for any future public package or API. | Wire semantics, external protocol contracts, internal implementation detail. |
@@ -125,11 +126,13 @@ other contracts.
 
 ### Releases
 
-`docs/release.md` owns the source-release procedure. Release notes are
+The [release policy](release.md) owns requirements and invariants; the
+[repository procedure](../release.md) owns the commands that satisfy them.
+Release notes are
 historical summaries, not current-state contract owners: the checked-in note at
 an immutable tag records that release, while current canonical documentation
-must change with the behavior it describes. Do not use a release note to defer
-or replace current documentation updates.
+must change with the behavior it describes. Do not use a release procedure or
+note to weaken policy, redefine current contracts, or defer documentation updates.
 
 ### Contracts And Implementation
 

docs/policy/release.md

@@ -0,0 +1,204 @@
+# Release Policy
+
+**Base Policy Version:** 1.1
+
+**Last Updated**: 2026-09-25
+
+**Upstream Source:** `policy` commit `45591a79004c6811950f14dca554f6ff69b7f58e`.
+
+Notarius adaptations: source-only delivery, lightweight tags, branch-before-tag
+publication, no prereleases, and the justified native command check below.
+
+## Purpose
+
+This policy defines a proportionate workflow for validating and publishing an
+intended source revision under a fresh version. Releases should require little
+routine intervention, avoid repeated work, and preserve published contents.
+
+The repository-specific commands belong in `docs/release.md`. Historical release
+summaries belong in `docs/releases/`. The procedure must agree with the adopted
+policy and link to it rather than introduce additional release requirements.
+
+## Release Model And Completion
+
+A source release identifies one exact committed source revision through an
+immutable version tag and a version-matched, checked-in release note. The
+primary release branch is `main` and the authoritative remote is `origin`.
+Tags are lightweight. Publish the candidate to `main` before pushing its tag.
+
+A successful push of the intended tag, with its source commit available on the
+authoritative primary branch, completes the release. Notarius uses
+branch-before-tag publication; it does not require an atomic push.
+
+Release commands must finish at successful publication. They must not wait for
+or poll CI, require successful CI status, inspect downloadable artifacts, or
+check consumer installation or Go module availability as completion gates.
+A failed or ambiguous push requires resolving the authoritative remote state
+before declaring success or retrying; successful pushes do not require a
+separate remote read-back gate.
+
+Notarius publishes source only: no binaries, archives, images, packages,
+checksums, signatures, or Gitea release objects. Tag CI may provide advisory
+validation but publishes no deliverables and is not a completion gate.
+
+## Versioning And Compatibility
+
+Stable releases use Semantic Versioning in the form `vMAJOR.MINOR.PATCH`, with
+no leading zeroes. Notarius does not support prereleases.
+
+The selected version must be unused locally and on the authoritative remote.
+Do not require queries to every configured remote or publication service.
+A version known to have already been published must not be reused, even if the
+normal guards do not inspect that channel. Adding a distribution channel
+requires a deliberate update to the policy and procedure where needed.
+
+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.
+
+Additional compatibility promises and deliberate exceptions belong in the
+adopted policy or canonical contract documentation. Release notes explain
+changes; they do not redefine current compatibility contracts.
+
+## Release Documentation And Preparation
+
+Every new release must include `docs/releases/<version>.md` in the tagged
+source tree. Use the complete version tag as the filename and begin with a
+title containing the product name and that exact version.
+
+Include a short summary and any relevant compatibility impact or upgrade
+instructions. Keep the note proportionate to the change. Fixed sections and
+explicit no-action boilerplate are not required. Existing historical notes
+need not be rewritten to adopt this format.
+
+Keep exact current contracts in their canonical documents and update affected
+documentation with the behavior change. Link to those documents from the note
+where useful. A release note must not substitute for current documentation.
+Do not create retrospective notes for the pre-procedure v0.1.0, v0.2.0, or
+v0.3.0 tags.
+
+Version selection, release-note content, and retirement of completed roadmaps
+are preparation responsibilities, not separate human approval gates. Preserve
+planned and deferred work and repair affected links when retiring roadmaps.
+Ordinary change review covers unintended files, credentials, and private data;
+do not repeat it as a release-specific sign-off. Ignored local files are not
+prohibited merely because they exist: they are not included in the tagged source.
+
+## Candidate Validation
+
+Provide one publication command that validates the final committed candidate,
+checks publication state, and publishes the intended refs. A validation-only
+mode or command may be provided for diagnosis, but must not be a required step
+before publication repeats the same checks.
+
+Run the complete deterministic, offline default test suite once for the final
+candidate, following the [testing policy](testing.md). For repositories that
+publish builds, verify the required build targets. Select those targets for
+the application's actual support commitments; native testing on each platform
+and access to particular hardware are not default release prerequisites.
+
+Additional gates must address a concrete risk that the existing checks do not
+adequately cover. Do not automatically require linting, race testing, module
+hygiene audits, documentation audits, credential scans, example validation, or
+expanded platform matrices solely because they are possible. Retain such
+checks when their distinct protection justifies their cost. A one-time migration
+check must not silently become a permanent release requirement.
+
+Release tests must not require real credentials, mutable application services,
+paid APIs, provider probes, or inference calls. The procedure may describe dependency
+preparation separately from offline validation.
+
+Avoid duplicate validation across release phases. Successful checks for the
+same final candidate need not be repeated solely to satisfy another phase;
+any reuse must clearly apply to that exact candidate. Persistent validation
+caches are not required. If the candidate changes, validate the new candidate.
+Cheap publication-state checks may be repeated immediately before pushing
+because local or remote state may have changed during validation.
+
+Automate mechanical guards. Human review gates are strongly disfavored: add one
+only through an explicit project-specific policy decision explaining the
+concrete risk and why ordinary change review or automation is insufficient.
+Do not add routine confirmations for checks the command can perform itself.
+
+### Notarius Gate Selection
+
+Run the default offline Go suite once and build the native `cmd/notarius` with
+release version injection, checking its `--version` output. The command check
+protects the actual executable entry point and linker-supplied version, which
+package tests alone do not verify. Build products are temporary, not published.
+Use `GOWORK=off` so a sibling checkout cannot substitute for declared dependencies.
+
+Race tests, standalone vet, formatting/whitespace checks, module tidy audits,
+standalone example validation, and Linux/Darwin cross-builds remain useful
+change-specific development checks, not mandatory release gates. Default tests
+already cover maintained examples. Source-only publication does not require a
+binary distribution matrix. No new platform or hardware prerequisites are added.
+
+## Publication Guards
+
+Automate the checks needed to publish the intended source under a fresh version:
+
+- the version has the adopted format and is unused locally and on the
+  authoritative remote;
+- the worktree and index are clean on the primary release branch;
+- the source being published is the exact candidate that passed validation,
+  including its matching release note;
+- the branch push advances authoritative `main` to the candidate without
+  discarding remote history, before the tag is published; and
+- the tag identifies the validated candidate and only the intended refs are
+  published.
+
+Fetch the authoritative branch and tag state as needed for these checks.
+Do not force branch or tag updates to bypass a failed guard. Publish explicit
+refs rather than all local tags. Do not require CI success, publication-service
+availability checks, or a separate manual confirmation for each guard.
+
+## Immutability And Failure Recovery
+
+Published version tags and published contents are immutable. Do not move,
+overwrite, recreate, or delete a published tag, or replace a published artifact,
+checksum, signature, provenance statement, or release note under that version.
+The checked-in note at the immutable tag is that release's historical record.
+
+If validation fails before publication, correct and commit the candidate and
+rerun the publication command. If a push fails or its outcome is ambiguous,
+inspect the authoritative remote before retrying. Remove an unpublished local
+tag only after confirming it was never published or used by a release channel.
+An unavailable remote leaves publication status unknown; do not overwrite a tag
+to resolve uncertainty.
+
+Transient network, authentication, CI, or consumer-availability failures do not
+by themselves require a new version. Advisory CI or optional installation checks
+may be retried against the same immutable tag. Notarius has no asynchronous
+artifact delivery to recover.
+
+A defect requiring changes to published source or contents requires a corrected
+commit, a new semantically appropriate version, a matching release note, and
+the release procedure again. Leave the original release intact. A channel's
+yank, deprecation, or advisory mechanism may warn consumers away from a defective
+release without replacing its contents or reusing its version.
+
+## Repository Release Procedure
+
+Maintain `docs/release.md` as a short, executable maintainer runbook. It must
+identify:
+
+1. prerequisites, primary branch, and authoritative remote;
+2. version and release-note preparation;
+3. one publication command with its selected local checks and automated guards;
+4. declared deliverables, required build targets, and automation responsibilities;
+5. the successful-push completion point and separately reported delivery status;
+   and
+6. failure handling and ambiguous-push recovery.
+
+Use copyable commands where practical. Keep optional diagnostics and consumer
+verification clearly optional. The procedure must not turn preparation work,
+ordinary change review, or post-publication investigation into additional
+release gates.