docs(release): establish the current preparation procedure

AGENTS.md

@@ -29,12 +29,29 @@ Push normal development branches to `swarm` and open PRs against
 `EffortlessMetrics/shiplog` clone in place for new normal work; clone
 `shiplog-swarm` side-by-side when setting up a fresh agent or machine.
 
-Promotion from swarm back to source uses a regular merge-commit PR into
-`EffortlessMetrics/shiplog/main`, not a squash merge. A promotion PR should
-include the swarm head SHA, included swarm PRs, and proof that
-`Shiplog Rust Small Result` passed. Use
+Promotion from swarm back to source uses `cargo xtask promote` and a regular
+merge-commit PR into `EffortlessMetrics/shiplog/main`, never a squash merge.
+Do not push raw `swarm/main` as a source promotion branch or rebuild the
+per-path overlay manually. Run the current exact-head dry-run twice, inspect the
+machine path decisions and included receipts, execute the idempotent command,
+and verify the landed checkpoint with `--verify-only`. A fail-closed result is
+a repair queue; do not bypass it with an older source ref or historical mode.
+Use
 [`plans/shiplog-swarm/promotion-runbook.md`](plans/shiplog-swarm/promotion-runbook.md)
-for the exact promotion sequence.
+for the complete promotion and closeout sequence.
+
+Shared release-candidate preparation also belongs in swarm. Finish the release
+scope, version and lockfile, changelog freeze, README/guides, release decision,
+readiness ledger, and handoff skeleton on `shiplog-swarm/main`, then promote the
+exact proven candidate. Source work begins only after that checkpoint and is
+limited to release execution, tagging, publication, and explicitly authorized
+source-owned writer configuration. Use
+[`docs/release/release-preparation.md`](docs/release/release-preparation.md) for
+the current preparation, preflight, tag, staged-artifact, publication,
+rollback, and closeout procedure. Versioned readiness/decision files and root
+`RELEASE_HANDOFF_*` files are historical receipts, not standing command
+references. A product or shared-documentation defect found on source returns to
+swarm and is promoted again.
 
 ## Code Review Standards
 

docs/README.md

@@ -10,15 +10,28 @@ history.
 - `docs/proposals/` owns problem framing, user value, alternatives, and success criteria.
 - `docs/specs/` owns required behavior, non-goals, acceptance, and proof obligations.
 - `docs/adr/` owns durable architecture decisions and consequences.
-- `plans/` owns PR-sized sequencing, proof commands, and rollback notes.
+- `plans/` owns PR-sized sequencing, proof commands, rollback notes, and the
+  source/swarm promotion transaction.
 - `.codex/goals/active.toml` owns current Codex execution state.
 - `docs/status/SUPPORT_TIERS.md` owns product-claim-to-proof mapping.
 - `policy/*.toml` owns enforceable ledgers and exceptions.
-- `docs/governance/` owns human guides to enforced repository-governance boundaries (e.g. [automation authority](governance/automation-authority.md)).
-- `docs/handoffs/` owns closeout outcomes and residual work.
+- `docs/governance/` owns human guides to enforced repository-governance
+  boundaries, including [automation authority](governance/automation-authority.md).
+- `docs/release/release-preparation.md` owns the living release-preparation,
+  staging, publication, and closeout procedure.
+- versioned files under `docs/release/` and root `RELEASE_HANDOFF_*` files own
+  historical release decisions and execution evidence, not current commands.
+- `docs/handoffs/` owns initiative closeout outcomes and residual work.
 
 ## Linking rule
 
 Every material initiative should be linked across the stack:
 
 `roadmap -> proposal -> spec -> ADR (if needed) -> plan -> active goal -> issue/PR -> proof and policy receipts`.
+
+A release adds a separate bounded evidence chain:
+
+`merged swarm candidate -> exact source promotion -> release decision -> readiness ledger -> immutable tag proof -> public-state handoff`.
+
+Start a new release from [`docs/release/README.md`](release/README.md). Do not
+copy standing instructions from a historical versioned release receipt.

docs/release/README.md

@@ -0,0 +1,66 @@
+# Shiplog Release Documentation
+
+This directory separates the **current release procedure** from historical
+release evidence.
+
+## Current procedure
+
+Use [`release-preparation.md`](release-preparation.md) for every new release.
+It owns the current order of operations, stop conditions, proof commands,
+publication boundary, rollback rules, and copyable checklists.
+
+Promotion from the development trunk into the public source repository is a
+separate prerequisite for source release execution. Use
+[`plans/shiplog-swarm/promotion-runbook.md`](../../plans/shiplog-swarm/promotion-runbook.md)
+for that exact-source/exact-swarm transaction.
+
+## Artifact roles
+
+| Surface | Role |
+| --- | --- |
+| `release-preparation.md` | Living preparation, staging, publication, and closeout procedure. |
+| `templates/` | Starting points for a new versioned readiness ledger and execution handoff. |
+| `<version>-release-decision.md` | Version-specific scope and release/no-release decision. |
+| `<version>-readiness.md` | Version-specific preflight and observed release evidence. |
+| `../../RELEASE_HANDOFF_<version>.md` | Version-specific execution and public-state handoff. |
+| `../../CHANGELOG.md` | User-visible release contents and version history. |
+
+Versioned files and root `RELEASE_HANDOFF_*` files are historical receipts.
+They may contain commands, workflow names, tools, versions, or repository state
+that were correct for that release but are no longer current. **Do not copy a
+historical command block into a new release.** Start from the living procedure
+and current templates, then record the commands and evidence actually used.
+
+## Authority boundary
+
+- `EffortlessMetrics/shiplog-swarm` owns normal product, documentation, test,
+  CI, policy, and shared release-candidate preparation: scope, version,
+  changelog freeze, README/guides, release decision, readiness ledger, and
+  handoff skeleton.
+- `EffortlessMetrics/shiplog` owns the public source lineage, release tags,
+  crates.io publication, GitHub Releases, signing, package-channel publication,
+  and security-sensitive release credentials.
+- A complete shared release candidate must be promoted from a proven exact
+  swarm head into source through a regular merge-commit checkpoint before
+  source release execution begins.
+- Source release preparation is narrow and source-owned: validate the promoted
+  candidate and adjust only explicitly authorized release-writer configuration
+  when necessary. A product or shared-documentation defect goes back to swarm.
+
+## Quick route
+
+1. On `shiplog-swarm`, finish the release scope, shared docs, version/lockfile,
+   changelog freeze, release decision, readiness ledger, and handoff skeleton.
+2. Prove the exact release candidate on `shiplog-swarm/main`.
+3. Promote that exact green swarm head with `cargo xtask promote`.
+4. Verify and close out the regular-merge source checkpoint.
+5. On current `shiplog/main`, run source preflight and merge only narrowly
+   required source-owned release-writer changes.
+6. Push one immutable annotated tag from the exact proven source commit.
+7. Require the source Release workflow to stage and validate one exact
+   four-platform candidate set while it remains non-current.
+8. Publish crates.io and make the GitHub release public only after the exact tag
+   workflow and terminal candidate-ready aggregate are green.
+9. Verify public assets and package channels, finalize the observed release
+   evidence, and back-port any source-only release documentation/workflow
+   changes to swarm before normal promotion resumes.