Document eligible original-job retries and artifact retention

Author: MariusStorhaug

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

@@ -54,3 +54,9 @@ Provide `GH_TOKEN` with contents-write access scoped to the consumer repository.
 NuGet-reserved container metadata paths are rejected in the tested candidate before a claim or upload, using the same path classification as raw package verification. A published package without its shared module/version coordinate is unproven; the publisher does not fabricate that ownership record on retry.
 
 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.
+
+## Retry eligibility
+
+The action downloads `ArtifactName` from the current workflow run. That name is not an immutable selector for an earlier producing run or attempt. A retry of the original failed publishing job can retain a proven Gallery package and continue GitHub completion only when it downloads the original tested bytes and preserves the original settings, source/context, and verifiable required test evidence. The original runtime must already include the ownership checks.
+
+A full or new workflow run can rebuild different bytes even at the same source and version, including when Build generates an omitted manifest `GUID`. Those bytes fail the original claim check; the action does not recover them by rewriting metadata, importing a Gallery package, or promoting an earlier artifact automatically. Missing or expired downloads fail, and missing or unverifiable source/test evidence makes the retry ineligible. See [Retry eligibility and artifact retention](../../../docs/content/guides/versioning-and-releases.md#retry-eligibility-and-artifact-retention) for retention, verification, and failure handling.

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

@@ -51,3 +51,9 @@ Release creation and upload recheck the release tag, shared module/version coord
 The local ZIP's exact bytes and payload digest are verified together against the tested file tree before claiming, creating, or uploading. Original event PR context and versioned provenance must have valid object/scalar shapes before normalization; arrays cannot supply publication ownership.
 
 Complete authored or generated notes for PR-produced stable and prerelease releases precede the same final repository/producing-PR/source footer. A matching tag/source does not authorize another PR's release, and an existing PR release without that proof is not resumed. Indented, inline, or unreadable terminal ownership markers fail explicitly. Direct stable releases retain their genuinely absent PR context. Legacy records without proof require reviewed forward-only recovery; the action does not fabricate provenance or alter consumer metadata.
+
+## Retry eligibility
+
+Missing release creation or asset upload can resume from the original proven tested artifact, with unchanged source, producing context, prefix, and resolved coordinates. The action downloads `ArtifactName` from the current run and does not select an earlier producing run/attempt/artifact or establish its completed-test provenance. Retry only an eligible original failed publishing job whose original runtime includes the ownership checks and whose artifact and required evidence remain available.
+
+The same source and version do not prove a rebuild has the original payload or ZIP bytes; an omitted manifest `GUID` can be generated differently by Build. Conflicting rebuilt bytes, missing or expired artifacts, and unproven source/test evidence prevent recovery. Do not replace published assets or edit consumer metadata to bypass those checks. See [Retry eligibility and artifact retention](../../../docs/content/guides/versioning-and-releases.md#retry-eligibility-and-artifact-retention) for the complete supported-retry contract.

.github/actions/Resolve-PSModuleVersion/README.md

@@ -20,7 +20,7 @@ The existing `Version`, `Prerelease`, `FullVersion`, `ReleaseType`, and `CreateR
 
 ## Recovery safety
 
-Only one exact source/context claim with matching raw package bytes can select a recovery version. An already-created GitHub release with a missing upload can resume through [Release-PSModule](../Release-PSModule/README.md). The publisher retains the proven Gallery package and verifies the rebuilt/tested artifact again before any write.
+Only one exact source/context claim with matching raw package bytes can select a recovery version. An already-created GitHub release with a missing upload can resume through [Release-PSModule](../Release-PSModule/README.md), but only from the original proven tested bytes. Selecting the original version does not make a rebuild byte-identical or select the original tested artifact.
 
 An unpublished shared-only claim still stops Plan for original-job retry, even after a later source completes another version. A new source checks baseline completeness using the actual historical tag and release, not a tag reconstructed with the current configured prefix. Recovery and new claims still require exact configured-prefix binding; ambiguous historical baselines stop explicitly.
 
@@ -35,3 +35,9 @@ Historical prefixes may contain digits, with or without a separator. A matching
 | Authentication or API lookup fails | Surface the error instead of treating it as absence. |
 
 Legacy incomplete publication requires reviewed forward-only recovery. Do not fabricate provenance, retarget existing tags, change consumer metadata, or choose a version from a moving/latest hint.
+
+## Retry eligibility
+
+Plan resolves coordinates, not original-run artifact selection or completed-test provenance. A full workflow rerun still executes enabled Build/test jobs; supported manifests without a `GUID` can produce different artifact bytes on that rebuild. Publication rejects those bytes rather than treating the resolved version as proof of recovery.
+
+An original failed-publishing-job retry is eligible only while its original artifact, settings, source/context, and required test evidence remain verifiable and its original runtime already contains the ownership checks. Missing or expired artifacts and unproven evidence do not authorize publication. See [Retry eligibility and artifact retention](../../../docs/content/guides/versioning-and-releases.md#retry-eligibility-and-artifact-retention) for the supported paths and the wrappers' current-run/name selection limits.

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

@@ -112,11 +112,59 @@ ambiguous claim, unavailable legacy proof, or API failure stops resolution witho
 For a new source, baseline completeness uses its actual historical tag/release, even when the configured prefix
 changes. Recovery and new claims still bind the current prefix exactly; ambiguous completed baseline tags fail.
 
-If Gallery publication succeeded and GitHub creation or upload failed, the retry retains that proven version,
-skips only the identical Gallery upload, and completes the missing GitHub work without replacing bytes.
-Build and tests still run, and the publisher rechecks the resulting artifact against the original claim.
-See the [resolver contract](https://github.com/PSModule/Process-PSModule/tree/main/.github/actions/Resolve-PSModuleVersion)
-for safe recovery failures and the original-job retry path.
+## Retry eligibility and artifact retention
+
+Version recovery and tested-artifact reuse are separate checks. If Gallery publication succeeds but GitHub creation
+or upload fails, Plan can select the proven original version. Completion still requires the original tested file
+tree and matching release ZIP, with the same immutable source, producing context, prefix, and resolved coordinates.
+Only the proven duplicate Gallery upload is skipped; published bytes are not replaced. See the
+[resolver contract](https://github.com/PSModule/Process-PSModule/tree/main/.github/actions/Resolve-PSModuleVersion)
+for version-selection failures.
+
+### Before retrying
+
+The original workflow/action revision must already contain the ownership checks. Retrying an older failed job
+does not install a later framework implementation: GitHub
+[reuses the first attempt's reusable-workflow commit for failed or specific job reruns](https://docs.github.com/en/actions/reference/workflows-and-actions/reusing-workflow-configurations#behavior-of-reusable-workflows-when-re-running-jobs).
+The original artifact and settings must remain available, and the caller or operator must be able to verify the
+required test, lint, and coverage results against that exact artifact. A matching version, artifact name, or
+successful-looking workflow conclusion alone is not completed-test evidence.
+
+The [Build action](https://github.com/PSModule/Process-PSModule/tree/main/.github/actions/Build-PSModule) retains its
+uploaded artifact for one day; the framework calls it `module`. The test, publish, and release wrappers download
+the named artifact from the current run. They do not expose an immutable original-run/attempt/artifact selector
+or a completed-test provenance contract for cross-run reuse. An artifact name, including a duplicate name from
+another attempt, is not proof that the selected bytes are the original tested artifact. Raw Gallery package
+verification establishes payload identity; it is not an original-artifact retrieval or promotion path.
+
+### Choose the retry path
+
+| Retry path | Supported behavior and limit |
+| --- | --- |
+| Only the original failed publishing job; no new Plan, Build, or test execution | Can reuse surviving original bytes and settings when the selected artifact, ownership, and required test evidence remain verifiable and the original runtime contains the safety checks. |
+| All jobs in the workflow | Enabled Build and test jobs run again, and downloads select that run's artifact. Resolving the original version does not guarantee the rebuilt artifact matches its original claim. |
+| A new full workflow run at the same source | Produces a new run/artifact rather than automatically selecting the original tested artifact. Whole-run or cross-run original-artifact recovery is not supplied by the wrappers. |
+| Missing or expired artifact, or unavailable/unverifiable source, context, or test evidence | Stop recovery. Do not infer success, invent a fallback version, or fabricate proof. Reviewed forward-only reconciliation is required when original proof cannot be retained. |
+
+A supported source manifest can omit `GUID`; Build then generates a GUID when creating the manifest. A clean
+rebuild can therefore change manifest, file-tree, and ZIP bytes even when the source and resolved version are
+unchanged. The publisher rechecks the resulting bytes against the original claim and fails on a mismatch.
+Do not insert or replace a consumer GUID or other metadata to force a same-source retry to match. A full rerun
+is not a substitute for retaining the original tested artifact.
+
+### Verify the retained evidence
+
+1. Confirm the selected artifact is the original available Build output and that its immutable source, original
+   settings, producing context, and resolved coordinates match the publication claim.
+2. Verify every required test, lint, and coverage result was completed for those exact bytes. The existing
+   [pipeline stages](../reference/pipeline-stages.md#framework-test) describe those checks; the publication claim's
+   byte digests do not replace their results.
+3. Retain the file-tree and exact ZIP proof. Publication rechecks must agree before another mutation; differing,
+   ambiguous, or unverifiable bytes fail rather than replacing a package, tag, or asset.
+
+Missing or expired artifacts fail the named download. Missing source/context/test evidence makes the retry
+ineligible even if some workflow jobs report success. Stop rather than relax ownership or byte checks,
+import package code as proof, edit metadata, or assume automatic selection of the original artifact.
 
 ## Linear versioning