Add source publication command and runbook

docs/cli.md

@@ -1,6 +1,6 @@
 # Command line
 
-ReleaseKit currently provides two commands.
+ReleaseKit currently provides three commands.
 
 Print the executable version:
 
@@ -24,7 +24,28 @@ captured local commit and version. It checks the committed release note, local
 Git state, and configured validation, but does not inspect remote availability
 or publish a tag.
 
-Both commands write errors and diagnostic output to standard error. `check`
-returns status 0 after local validation, 1 after a candidate validation failure,
-and 2 for usage, profile, or invalid-version errors. Unsupported argument
-sequences print usage to standard error.
+`check` writes errors and diagnostics to standard error. It returns status 0
+after local validation, 1 after a candidate validation failure, and 2 for usage,
+profile, or invalid-version errors. Unsupported argument sequences print usage
+to standard error.
+
+Publish a source tag:
+
+```sh
+go run ./cmd/releasekit publish [--repo DIR] [--config FILE] VERSION
+```
+
+`publish` reads the same product, remote, and validation settings as `check`.
+It validates the candidate once, checks the authoritative remote, creates an
+annotated local tag, and pushes only its exact tag object. It prints the
+confirmed version, candidate commit, and tag object on success. Validation
+progress and failed publication state are written to standard error. A signal
+cancels the active operation; if it arrives during a push, the library's
+bounded reconciliation determines whether the exact tag was accepted.
+
+The command returns status 0 for confirmed publication, 1 for a known
+publication failure or conflict, 2 for usage, profile, or invalid-version
+errors, and 3 when the push outcome remains unknown. Unknown status must be
+resolved against the authoritative remote before retrying. The
+[maintainer procedure](release.md) selects the repository profile and gives
+the source-release workflow.

docs/config.md

@@ -20,10 +20,12 @@ The overlay does not modify the ReleaseKit process environment.
 
 Unknown fields are rejected so a setting cannot be silently ignored. Build and
 delivery fields will be added when those operations are implemented. The `check`
-command uses `product`, `remote`, and `checks`. If `checks` is omitted or empty,
-it runs `go test -mod=readonly -count=1 ./...` with Go module and toolchain
-network access disabled. If checks are configured, they replace that default and
-run in order.
+and `publish` commands use `product`, `remote`, and `checks`. If `checks` is
+omitted or empty, it runs `go test -mod=readonly -count=1 ./...` with Go module
+and toolchain network access disabled. If checks are configured, they replace
+that default and run in order.
 
+ReleaseKit's source-only publication profile is
+[releasekit.json](../releasekit.json).
 See the [profile example](../examples/releasekit.json). The
 [CLI contract](cli.md) lists the currently available command.

docs/development.md

@@ -65,7 +65,9 @@ git diff --cached --check -- '*.md' COPYRIGHT
 Verbatim license texts retain their supplied formatting. When changing those
 texts, compare their bytes with the selected upstream source.
 
-There is no publication command yet. Add working development commands here as
-implementation lands. Add `docs/release.md` with the first working publication
-command; the [policy adoption roadmap](roadmap/policy.md#4-define-releasekits-own-release-path)
-records the remaining bootstrap work.
+Run the source publication command from the candidate repository root with
+`./scripts/release VERSION`. It uses the local Go toolchain and committed
+`releasekit.json` profile; prepare module dependencies before offline candidate
+validation. The [maintainer release procedure](release.md) owns preparation,
+publication, and recovery. Executable artifacts and delivery remain outside
+ReleaseKit's initial source-only release.

docs/policy/release.md

@@ -18,10 +18,8 @@ policy and link to it rather than introduce additional release requirements.
 
 This policy governs releases of ReleaseKit itself. Consumer release capabilities
 are designed in the [product roadmap](../roadmap/releasekit.md) and acquire exact
-public contracts when implemented. ReleaseKit currently has no publication
-command. Create the maintainer runbook alongside the first working command;
-the [policy adoption roadmap](../roadmap/policy.md#4-define-releasekits-own-release-path)
-owns that pending work.
+public contracts when implemented. ReleaseKit's source publication command and
+maintainer runbook are implemented; no ReleaseKit release has been published.
 
 ## Release Model And Completion
 
@@ -33,8 +31,8 @@ The procedure must name the authoritative publication remote.
 A successful push of the intended annotated tag, with its source commit already
 published on authoritative `main`, completes the release. The remote branch must
 identify the validated candidate before the command publishes only the exact
-intended tag object. The runbook will identify the authoritative endpoint and
-command when publication is implemented.
+intended tag object. The [maintainer runbook](../release.md) identifies the
+authoritative endpoint and command.
 
 Release commands must finish at successful publication. They must not wait for
 or poll CI, require successful CI status, inspect downloadable artifacts, or

docs/release.md

@@ -0,0 +1,93 @@
+# ReleaseKit release procedure
+
+ReleaseKit's initial deliverable is source only. The authoritative repository
+is `origin` at `https://gitea.maximumdirect.net/eric/ReleaseKit.git`, and the
+release branch is `main`. A release completes when the intended annotated tag
+is successfully pushed, or when one exact-object recovery query confirms that
+the push succeeded. CI, hosted artifacts, and consumer installation are not
+completion checks.
+
+## Prepare a candidate
+
+Use a local Go 1.25 toolchain and a clean clone. Start on `main`, choose an
+unused stable `vMAJOR.MINOR.PATCH` version, and add
+`docs/releases/<version>.md` with a first heading containing `ReleaseKit` and
+the exact version. Summarize the change and any compatibility or upgrade impact.
+End the note with the three license links at the immutable source tag:
+
+```markdown
+[COPYRIGHT](https://gitea.maximumdirect.net/eric/ReleaseKit/src/tag/vX.Y.Z/COPYRIGHT) |
+[LICENSE](https://gitea.maximumdirect.net/eric/ReleaseKit/src/tag/vX.Y.Z/LICENSE) |
+[ATTRIBUTION](https://gitea.maximumdirect.net/eric/ReleaseKit/src/tag/vX.Y.Z/docs/oss/attribution.md)
+```
+
+Replace every `vX.Y.Z` with the selected version. These are links to the same
+release note's immutable source tree and also work when the note is used as a
+hosted release body.
+
+Commit the note and all candidate changes on `main`, then publish that commit
+to `origin/main`:
+
+```sh
+git push origin main
+```
+
+ReleaseKit checks that the worktree is clean, the candidate is on `main`, the
+authoritative branch identifies that commit, and the version is unused locally
+and on `origin`.
+
+## Prepare dependencies, then publish
+
+Dependency preparation is separate from the offline candidate validation. Run
+it from the captured candidate source before the release command:
+
+```sh
+GOTOOLCHAIN=local go mod download
+```
+
+Then run the single publication command from the repository root:
+
+```sh
+./scripts/release vX.Y.Z
+```
+
+The committed `releasekit.json` selects the offline default test suite:
+`go test -mod=readonly -count=1 ./...`, with toolchain and module network
+access disabled for validation. The command validates once, checks the
+authoritative remote state, creates a local annotated tag from the captured
+candidate and checked-in note, rechecks the tag and remote guards, and pushes
+only that tag object. It prints the published version, commit, and tag object
+on success. Exit status 0 means publication is confirmed; status 1 means a
+known failure or conflict; status 2 means invalid input or profile; status 3
+means the push outcome remains unknown and requires resolution.
+
+The CLI runs from the source tree being published, so this command also works
+for ReleaseKit's first release before any released ReleaseKit executable
+exists. It uses the local Go toolchain. Preparation must finish before the
+offline validation begins.
+
+## Resolve failures
+
+A failed push triggers one exact authoritative tag query. An exact tag-object
+match confirms publication even when Git reported an error. A proven absent tag
+is `not_published`; a different object is a conflict; an unreadable query is
+`unknown`. The command retains its local tag and reports the state, phase,
+candidate commit, and tag object when available. Do not retry an unknown result
+until you resolve the authoritative ref:
+
+```sh
+git ls-remote --refs origin "refs/tags/vX.Y.Z"
+```
+
+Compare the returned object ID with the tag object reported by the command.
+An exact match confirms publication. If the ref is absent, the version was not
+published; only then may you deliberately remove the unpublished local tag
+with `git tag -d vX.Y.Z` before correcting the candidate or retrying. Do not
+move, overwrite, or delete a tag that exists remotely. If a different object
+uses the version, choose a new version after resolving the conflict.
+
+If validation or a guard fails before the push, the local tag has not been
+published. Correct and commit the candidate, publish `main`, and run the
+command again. ReleaseKit does not publish executable artifacts or wait for
+asynchronous delivery; any future deliverables require a separate policy and
+procedure update.

docs/roadmap/implementation.md

@@ -649,7 +649,7 @@ local tag before push prevent publication.
 
 ## Stage 9: Expose publication and document ReleaseKit bootstrap
 
-Status: Pending. Depends on Stage 8.
+Status: Complete. Depends on Stage 8.
 
 1. Wire the complete public publisher into `releasekit publish`, with selected
    progress output, final result, exit classification, and signal cancellation.
@@ -672,6 +672,15 @@ committed profile and returns the expected exit/output behavior. Runbook command
 are exercised using a temporary repository configured like ReleaseKit. This
 stage prepares self-publication and does not publish a real ReleaseKit release.
 
+Evidence: `publish` runs the public publisher with the CLI signal context,
+selected progress output, final commit and tag-object output, and separate exit
+status for unresolved outcomes. A temporary committed profile runs the offline
+test command and publishes to a local bare remote. ReleaseKit's root profile,
+entry script, CLI and configuration guides, development guide, and maintainer
+runbook describe source-only publication and exact-object recovery. The
+runbook's dependency preparation is separate from offline validation. No real
+ReleaseKit release was published.
+
 ## Stage 10: Build selected targets with shared version injection
 
 Status: Pending. Depends on Stage 9.

docs/roadmap/policy.md

@@ -1,6 +1,8 @@
 # Adopt the policy framework
 
-Status: Policy adoption complete. Release publication implementation is pending.
+Status: Policy adoption complete. Source publication and its maintainer runbook
+are implemented; no ReleaseKit release has been published. Executable delivery
+remains pending.
 
 Date: 2026-10-05
 
@@ -130,20 +132,21 @@ policy has separate defaults for applications and libraries.
   successful-tag-push completion rules.
 - [x] Select source only as ReleaseKit's initial deliverable in the release
   policy. Supporting downstream cross-builds does not declare ReleaseKit binaries.
-- [ ] Add `docs/release.md` alongside the first working publication command,
+- [x] Add `docs/release.md` alongside the first working publication command,
   documenting real prerequisites, authoritative remote, branch, validation,
   publication, and failure recovery.
 - [x] Account for first-release bootstrap: the initial publication command must
   run from the captured candidate source with dependencies prepared separately.
   The first release uses that source execution path before a released ReleaseKit
-  tool exists. Document and verify the actual command when it is implemented.
+  tool exists. The maintainer procedure documents the command and the temporary
+  repository integration test exercises the same CLI workflow.
 - [ ] Add executable delivery declarations and target checks when corresponding
   deliverables exist. Keep source completion and asynchronous delivery status
   separate. This task is deferred unless executable deliverables are selected.
 
-The publication command, its automated guards and offline candidate validation,
-and the executable maintainer runbook remain product implementation work. This
-adoption does not claim an available release command or perform publication.
+The publication command, its automated guards, offline candidate validation,
+and executable maintainer runbook are implemented. This adoption does not claim
+that a ReleaseKit version has been published.
 
 ## Validation and completion
 
@@ -165,14 +168,14 @@ approval, and CI polling are not additional adoption or release gates.
 ## Adoption result
 
 The seven policies, root agent orientation, developer reading guide, documentation
-ownership, project grant, attribution, and license texts are in place. The product
-proposal lives at `docs/roadmap/releasekit.md`; `ideas.md` remains a navigation
-pointer. Future capabilities retain their proposed status, and facade
-implementation remains pending in the product roadmap.
+ownership, project grant, attribution, license texts, source publication command,
+and maintainer runbook are in place. The product proposal lives at
+`docs/roadmap/releasekit.md`; `ideas.md` remains a navigation pointer. Executable
+delivery remains pending, and no ReleaseKit release has been published.
 
 Verification covers local file and fragment links, per-policy source revision and
 base version, removed template adoption sections, attribution scope and pinned
 notice destinations, verbatim license bytes, and prose whitespace. The preserved
 ADR decision and relocated proposal are checked against their pre-adoption source.
-Release automation and its runbook remain pending under stage 4 as permitted by
-this roadmap's completion criteria.
+ReleaseKit's source publication command and runbook are implemented; executable
+delivery declarations remain pending under stage 4.

docs/roadmap/releasekit.md

@@ -1,9 +1,11 @@
 # ReleaseKit: shared release process
 
 This is a proposal based on a review of PromptKit, ConfigKit, Audita, Notarius,
-Narratio, and Scriptorium on 2026-09-29. Product capabilities remain proposed.
-The public facade architecture is accepted in
-[ADR 0001](../adr/0001-public-facade.md), with implementation pending.
+Narratio, and Scriptorium on 2026-09-29. The implementation plan records the
+current implemented boundary; builds, delivery, and broader integrations remain
+proposed. The public facade architecture is accepted in
+[ADR 0001](../adr/0001-public-facade.md) and is implemented for runtime version,
+candidate validation, and source publication.
 The [implementation plan](implementation.md) owns ordered stages, execution
 instructions, acceptance checks, and progress toward this target state.
 
@@ -50,12 +52,11 @@ cleanup.
 ## Architecture
 
 [ADR 0001](../adr/0001-public-facade.md) owns the accepted facade decision.
-The [architecture policy](../policy/architecture.md) owns the adopted responsibility
-and dependency rules, including the runtime version boundary. The facades remain
-unimplemented.
-The root `releasekit` package will provide the public facade for publication,
-builds, and delivery. A separate public `buildinfo` package will provide the
-lightweight facade for runtime version information.
+The [architecture policy](../policy/architecture.md) owns the adopted
+responsibility and dependency rules, including the runtime version boundary.
+The root `releasekit` package provides the public facade for candidate
+validation and source publication; builds and delivery remain planned. The
+separate public `buildinfo` package provides lightweight runtime version access.
 
 Each facade owns its public named types and documented contracts. Public
 operations, inputs, outcomes, errors, and callbacks express deliberately