Document source-bound publication and immutable retry requirements

Author: MariusStorhaug

.github/actions/Publish-PSModule/README.md

@@ -1,6 +1,10 @@
 # Publish-PSModule
 
-Publishes a pre-versioned PowerShell module artifact to the PowerShell Gallery. GitHub Release creation is intentionally handled by the separate [Release-PSModule](../Release-PSModule/README.md) action.
+Publishes a pre-versioned, tested PowerShell module artifact to the PowerShell Gallery after source-bound ownership preflight. GitHub Release creation is handled by the separate [Release-PSModule](../Release-PSModule/README.md) action.
+
+The publisher verifies the original source, exact resolved tag/version, producing repository/PR or direct-release context, and tested bytes before an external versioned-artifact mutation. An absent version is reserved with a create-only annotated tag containing the file-tree and ZIP SHA-256 proof. Existing tags are never updated or deleted.
+
+An existing Gallery package is retained only when its raw nupkg payload matches that proof and the tested artifact. Package code is never imported to establish ownership. Unknown legacy proof, foreign tags/releases/assets, changed claims, authentication errors, and API failures stop publication explicitly.
 
 ## Inputs
 
@@ -10,6 +14,9 @@ Publishes a pre-versioned PowerShell module artifact to the PowerShell Gallery.
 | `ModulePath` | Path containing the built `<Name>/` module directory. | No | `.PSModule/module` |
 | `ArtifactName` | Name of the module artifact to download. | No | `module` |
 | `PSGALLERY_API_KEY` | PowerShell Gallery API key. | Yes | N/A |
+| `ReleaseTag` | Exact tag already resolved as `Publish.Module.Resolution.FullVersion`. | Yes | N/A |
+| `CommitSha` | Immutable commit that produced the tested artifact. | No | Original workflow `GITHUB_SHA` |
+| `PullRequest` | Normalized producing-PR context; empty for a direct stable release. | No | Empty |
 | `WhatIf` | Logs publishing operations without publishing the module. | No | `false` |
 | `WorkingDirectory` | Directory where the publishing script runs. | No | `.` |
 
@@ -27,6 +34,11 @@ This action does not provide outputs.
     ModulePath: .PSModule/module
     ArtifactName: module
     PSGALLERY_API_KEY: ${{ secrets.PSGALLERY_API_KEY }}
+    ReleaseTag: ${{ fromJson(inputs.Settings).Publish.Module.Resolution.FullVersion }}
+    CommitSha: ${{ fromJson(inputs.Settings).Context.CommitSha }}
+    PullRequest: ${{ toJson(fromJson(inputs.Settings).Context.PullRequest) }}
 ```
 
-Use [Release-PSModule](../Release-PSModule/README.md) in a separate workflow step to create the GitHub release from the same artifact.
+Provide `GH_TOKEN` with contents-write access scoped to the consumer repository. The reusable workflow supplies its existing GitHub App token and resolved context internally.
+
+Use [Release-PSModule](../Release-PSModule/README.md) in a separate step to create the GitHub release from the same source and tested artifact. A retry must retain the original coordinates and bytes; unproven legacy publication requires reviewed forward-only recovery, not numeric guessing, retagging, or metadata changes.

.github/actions/Release-PSModule/README.md

@@ -1,6 +1,6 @@
 # Release-PSModule
 
-Creates or resumes a GitHub release for a pre-versioned PowerShell module artifact. The action attaches the exact built module ZIP to the release and reports the result on the source pull request.
+Creates or resumes a GitHub release for a pre-versioned, tested PowerShell module artifact. The action verifies the same immutable source/context/artifact claim as the Gallery publisher, attaches repeatable module ZIP bytes, and reports the result on the producing pull request when available.
 
 ## Inputs
 
@@ -10,6 +10,8 @@ Creates or resumes a GitHub release for a pre-versioned PowerShell module artifa
 | `ModulePath` | Path containing the built `<Name>/` module directory. | No | `.PSModule/module` |
 | `ArtifactName` | Name of the module artifact to download. | No | `module` |
 | `ReleaseTag` | Full GitHub release tag resolved by `Resolve-PSModuleVersion`. | Yes | N/A |
+| `CommitSha` | Original immutable build source for stable and prerelease tags. | No | Original workflow `GITHUB_SHA` |
+| `PullRequest` | Normalized producing-PR context; empty for a direct stable release. | No | Empty |
 | `WhatIf` | Logs release operations without creating or uploading anything. | No | `false` |
 | `WorkingDirectory` | Directory where the release script runs. | No | `.` |
 | `UsePRTitleAsReleaseName` | Uses the pull request title as the release name. | No | `false` |
@@ -36,6 +38,12 @@ Pass the Plan job's resolved `FullVersion` as `ReleaseTag` so the configured tag
     ModulePath: .PSModule/module
     ArtifactName: module
     ReleaseTag: ${{ fromJson(inputs.Settings).Publish.Module.Resolution.FullVersion }}
+    CommitSha: ${{ fromJson(inputs.Settings).Context.CommitSha }}
+    PullRequest: ${{ toJson(fromJson(inputs.Settings).Context.PullRequest) }}
 ```
 
-The action requires a `pull_request` event and a built module artifact. If a release already exists for `ReleaseTag`, it resumes by replacing the module ZIP, which makes retrying a partial release safe.
+The action supports normalized pull-request context and direct stable releases. Provide repository-scoped contents-write `GH_TOKEN` access and the original tested artifact/source. Tags resolve to actual commits, including annotated tags; mutable branch names and release target hints are not ownership proof.
+
+Release creation and upload recheck the tag, provenance, and artifact identity. A missing upload can resume. An existing asset is retained only when its published SHA-256 matches the exact local ZIP; differing, ambiguous, or unverifiable bytes stop the action. Uploads never use `--clobber`, and tags are never retargeted.
+
+Complete authored or generated prerelease notes precede a final repository/producing-PR/source footer. A matching tag/source does not authorize another PR's release. Legacy records without proof require reviewed forward-only recovery; the action does not fabricate provenance or alter consumer metadata.

docs/content/guides/versioning-and-releases.md

@@ -73,6 +73,27 @@ Each publication produces three linked, immutable artifacts:
 Release names and notes can be generated from the pull request — see
 [Configuring the pipeline](configuring-the-pipeline.md).
 
+## Publication ownership
+
+Before taking a Gallery version, the publisher verifies the immutable consumer source, the Plan job's exact
+resolved version/tag, the producing repository/PR or direct-release context, and the tested module bytes.
+An absent version tag is reserved with a create-only annotated claim containing the tested file-tree and
+release-ZIP SHA-256 digests. Existing tags are not updated or deleted.
+
+Standalone tags, annotated tags, releases, provenance footers, module assets, and exact Gallery packages must
+agree with that claim. Raw nupkg files are read without importing package code. Verified absence is different
+from an authentication/API failure or unknown ownership proof; errors and unavailable proof stop publication.
+
+The publisher rechecks the claim and tested files immediately before Gallery upload. GitHub release creation
+and upload repeat the ownership checks. Missing uploads may resume, identical published ZIP bytes are retained,
+and differing or unverifiable assets are never clobbered. Complete authored or generated prerelease notes remain
+before their final producing-repository/PR/source footer.
+
+A retry retains the original source, resolved coordinates, release context, and tested bytes. Legacy incomplete
+publications without proof require reviewed forward-only recovery, not a guessed version, retagging, asset
+replacement, or metadata edits. See the [publisher](https://github.com/PSModule/Process-PSModule/tree/main/.github/actions/Publish-PSModule)
+and [release action](https://github.com/PSModule/Process-PSModule/tree/main/.github/actions/Release-PSModule) contracts.
+
 ## Linear versioning
 
 Only a single linear ancestry of versions is maintained. Old versions are not patched: if a security issue is found on