docs: define Gallery prerelease recovery

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Author: MariusStorhaug

docs/content/reference/process-workflow-lifecycle-design.md

@@ -15,7 +15,7 @@ The confirmed reusable workflow runs a `Plan` job, enriches one settings object
 
 The version resolver treats non-pull-request events, including `workflow_dispatch` and `schedule`, as events without a release decision. The workflow's concurrency identity contains either the pull request number or the Git ref, and its runs are not canceled. The documented scenario matrix also identifies closed-pull-request cleanup as non-stable behavior.
 
-These facts establish the starting point. They do not implement the scheduled validation or manual recovery behavior proposed below.
+The current code detects an existing published version, resumes GitHub Release creation, and repeats GitHub Release and tag cleanup. Full reconciliation of immutable PowerShell Gallery prereleases is a design gap: it requires implementation and cancellation-boundary tests. These facts establish the starting point. They do not implement the scheduled validation or manual recovery behavior proposed below.
 
 ## Candidate event routing
 
@@ -80,14 +80,25 @@ Cancellation can leave only transient partial state. Every pull-request route, i
 
 | External operation | Required recovery behavior |
 | --- | --- |
-| PowerShell Gallery publication | Detect the existing resolved version and continue without duplicate publication. |
+| PowerShell Gallery publication | Use a deterministic pull-request-scoped prerelease identity, detect the existing resolved version, and continue without duplicate publication. |
 | GitHub Release creation | Resume or upsert the release and replace its asset set. |
 | Prerelease cleanup | Repeat safely after partial deletion and converge to the latest pull-request state. |
 | Prerelease lifecycle | A subsequent synchronize, label, unlabel, or close reconciles obsolete prereleases. |
 | Production boundary | No pull-request event creates a stable or signable production artifact. |
 
 Cleanup receives a pull-request-scoped artifact set and MUST NOT perform a broad prerelease deletion while a stable release can be active. Any future broad cleanup needs a separately approved exclusive scope; it cannot share the abandoned-close route.
 
+## Candidate Gallery prerelease disposition
+
+PowerShell Gallery packages are immutable and cannot be overwritten. Gallery reconciliation is therefore separate from GitHub Release and tag cleanup:
+
+| Obsolete Gallery prerelease condition | Candidate disposition |
+| --- | --- |
+| A supported Gallery API can unlist the version | Unlist the immutable package through that API. |
+| Unlisting is not feasible | Retain the immutable version and record it as retained in the lifecycle result. |
+
+The selected disposition policy remains unapproved. A cancellation can leave a published immutable package even when its GitHub Release and tag cleanup has not completed; the next pull-request event must detect that version and apply the approved Gallery disposition rather than attempting to overwrite it.
+
 ## Candidate verification strategy
 
 The lifecycle contract is exercised with event payload fixtures and publication fakes before credentials are used:
@@ -99,6 +110,7 @@ The lifecycle contract is exercised with event payload fixtures and publication
 | Recovery release notes | Merged-pull-request query fixtures covering an empty range, one pull request, and multiple pull requests. |
 | Scheduled validation | A published-version fixture that proves no release mutation is requested. |
 | Pull-request convergence | Canceled prerelease-publication and cleanup fixtures followed by synchronize, label, unlabel, and close events that prove the latest pull-request state is reconciled. |
+| Gallery immutability | Deterministic pull-request identity, existing-version detection, supported-unlist, and retained-version fixtures across the cancellation boundary. |
 | Non-pull-request serialization | Overlapping main-push, manual-dispatch, and scheduled fixtures that prove runs queue by ref and do not cancel. |
 
 ## Decisions requiring approval
@@ -109,6 +121,7 @@ The candidate does not decide the following:
 - Which source is authoritative when a PowerShell Gallery publication and GitHub release disagree about the last published stable version.
 - Which consumer-facing checks comprise scheduled published-artifact validation.
 - Whether removing prerelease eligibility cleans up existing prereleases immediately or leaves them until the abandoned-close cleanup route.
+- Whether the supported Gallery API can unlist obsolete prereleases; otherwise, how retained immutable versions are recorded.
 - Approval of the selected caller concurrency expression in [PSModule/Process-PSModule#514](https://github.com/PSModule/Process-PSModule/issues/514).
 
 ## Related

docs/content/reference/process-workflow-lifecycle-specification.md

@@ -149,6 +149,25 @@ Scenario: Reject an incorrectly stamped artifact
   And no release is made visible for that artifact
 ```
 
+### FR8 — Pull-request prereleases MUST have deterministic scoped identities {#fr8}
+
+A pull-request prerelease MUST use a deterministic identity scoped to its pull request. Reprocessing the same pull-request state MUST resolve the same prerelease identity, and different pull requests MUST NOT resolve the same identity.
+
+#### Behavioral scenarios {#fr8-scenarios}
+
+```gherkin
+Scenario: Reprocess the same pull-request state
+  Given a pull request has resolved a prerelease identity
+  When the same pull-request state is processed again
+  Then the workflow resolves the same prerelease identity
+  And it detects an existing publication instead of attempting an overwrite
+
+Scenario: Publish prereleases for distinct pull requests
+  Given two pull requests are eligible for prerelease publication
+  When both pull requests are processed
+  Then each pull request resolves a distinct prerelease identity
+```
+
 ## Non-functional requirements
 
 ### NFR1 — Lifecycle mutations MUST be idempotent {#nfr1}
@@ -201,7 +220,7 @@ Scenario: Inspect a scheduled validation result
 
 ### NFR4 — Pull-request mutation paths MUST resume and converge {#nfr4}
 
-Every pull-request path, including prerelease publication and cleanup, MUST be idempotent and resumable after cancellation. The next `synchronize`, `labeled`, `unlabeled`, or `closed` event MUST converge release-related state to the latest pull-request state. Cancellation MAY leave transient partial state, but it MUST NOT leave a permanent duplicate or obsolete artifact.
+Every pull-request path, including prerelease publication and cleanup, MUST be idempotent and resumable after cancellation. The next `synchronize`, `labeled`, `unlabeled`, or `closed` event MUST converge release-related state to the latest pull-request state. Cancellation MAY leave transient partial state, but it MUST NOT leave a permanent duplicate or an obsolete artifact without the required disposition.
 
 #### Behavioral scenarios {#nfr4-scenarios}
 
@@ -216,7 +235,7 @@ Scenario: Reconcile obsolete prereleases
   Given a canceled pull-request run left prerelease artifacts for an earlier pull-request state
   When a synchronize, label, unlabel, or close event is processed
   Then the workflow reconciles prerelease artifacts to the latest pull-request state
-  And no obsolete prerelease artifact remains after reconciliation
+  And every obsolete prerelease has the required disposition
 ```
 
 ### NFR5 — Pull-request events MUST NOT produce production artifacts {#nfr5}
@@ -233,6 +252,28 @@ Scenario: Evaluate an eligible prerelease pull request
   And it does not create a stable or signable production artifact
 ```
 
+### NFR6 — Immutable Gallery prereleases MUST have a disposition policy {#nfr6}
+
+PowerShell Gallery packages MUST be treated as immutable and MUST NOT be overwritten. The candidate MUST define whether obsolete pull-request prereleases are unlisted through a supported Gallery API or retained as documented immutable versions when unlisting is not feasible. This policy is distinct from GitHub Release and tag cleanup.
+
+#### Behavioral scenarios {#nfr6-scenarios}
+
+```gherkin
+Scenario: Dispose of an obsolete Gallery prerelease
+  Given a pull-request prerelease is obsolete
+  And a supported Gallery API can unlist that version
+  When the prerelease is reconciled
+  Then the workflow unlists the immutable Gallery package
+  And it performs GitHub Release and tag cleanup independently
+
+Scenario: Retain an immutable Gallery prerelease
+  Given a pull-request prerelease is obsolete
+  And unlisting that Gallery version is not feasible
+  When the prerelease is reconciled
+  Then the workflow records the retained immutable Gallery version
+  And it performs GitHub Release and tag cleanup independently
+```
+
 ## Cross-cutting acceptance criteria
 
 ### AC1 — Verifies: [FR1](#fr1), [FR6](#fr6), [FR7](#fr7), [NFR1](#nfr1)
@@ -247,7 +288,7 @@ Scenario: Recover release notes after a missed main-push publication
   And a retry creates no duplicate publication
 ```
 
-### AC2 — Verifies: [FR2](#fr2), [FR4](#fr4), [FR5](#fr5), [FR6](#fr6), [NFR2](#nfr2), [NFR3](#nfr3), [NFR4](#nfr4), [NFR5](#nfr5)
+### AC2 — Verifies: [FR2](#fr2), [FR4](#fr4), [FR5](#fr5), [FR6](#fr6), [FR8](#fr8), [NFR2](#nfr2), [NFR3](#nfr3), [NFR4](#nfr4), [NFR5](#nfr5), [NFR6](#nfr6)
 
 ```gherkin
 Scenario: Lifecycle runs preserve release ownership after cancellation