docs: select resumable PR concurrency

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

Author: MariusStorhaug

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

@@ -19,19 +19,19 @@ These facts establish the starting point. They do not implement the scheduled va
 
 ## Candidate event routing
 
-The planner classifies the caller event before build and publication work begins. Each route produces one of three mutation classes: validation only, prerelease mutation, or stable-release mutation. The candidate also assigns an explicit mutability mode, because callers cannot safely infer it from labels alone.
+The planner classifies the caller event before build and publication work begins. Each route produces one of three mutation classes: validation only, prerelease mutation, or stable-release mutation. Pull-request events may cancel their predecessors, so every pull-request route must converge to the latest pull-request state.
 
-| Event | Candidate route | Mutability mode | Cancellation | Required result |
+| Event | Candidate route | Mutation class | Cancellation | Required result |
 | --- | --- | --- | --- | --- |
 | `workflow_dispatch` on the default branch | Recovery release | Stable release or explicit no-op | Never cancel | Rebuild and validate the selected commit; reconstruct the unreleased release notes. |
-| `schedule` | Published-artifact validation | Validation only | May cancel only another explicitly read-only validation; never cancel a default-branch release | Validate the latest published stable artifact and its documentation. |
-| Pull request `opened`, `reopened`, `synchronize` | Pull-request CI | Explicitly read-only | May cancel a superseded run in the same read-only CI domain | Report configured validation on the pull request. |
-| Pull request `labeled`, `unlabeled` | Prerelease evaluation | Potential prerelease mutation | Never cancel | Re-evaluate the full label set and publish only an eligible prerelease. |
-| Merged pull request `closed` | Post-merge close | Validation only | May cancel only when explicitly routed as read-only | Do not clean up; the successful main-push release owns promotion cleanup. |
-| Abandoned pull request `closed` | Pull-request cleanup | Prerelease cleanup only | Never cancel | Remove only prereleases owned by the abandoned pull request. |
+| `schedule` | Published-artifact validation | Validation only | Never cancel | Validate the latest published stable artifact and its documentation. |
+| Pull request `opened`, `reopened`, `synchronize` | Pull-request CI | Validation only | Cancels a superseded pull-request run; the later run converges state | Report configured validation on the pull request. |
+| Pull request `labeled`, `unlabeled` | Prerelease evaluation | Prerelease or validation only | Cancels a superseded pull-request run; the later run converges state | Re-evaluate the full label set and publish only an eligible prerelease. |
+| Merged pull request `closed` | Post-merge close | Validation only | Cancels a superseded pull-request run; the later run converges state | Do not clean up; the successful main-push release owns promotion cleanup. |
+| Abandoned pull request `closed` | Pull-request cleanup | Prerelease cleanup only | Cancels a superseded pull-request run; the later run converges state | Remove only prereleases owned by the abandoned pull request. |
 | Push to the default branch | Stable release | Stable release | Never cancel | Resolve merged-pull-request intent when applicable, then publish and perform promotion cleanup after required gates. |
 
-The classifier records the route, mutability mode, mutable resource scope, commit identity, and release decision in the plan result. Downstream jobs consume that record rather than infer the event again.
+The classifier records the route, mutable resource scope, commit identity, and release decision in the plan result. Downstream jobs consume that record rather than infer the event again.
 
 ## Candidate artifact and version boundary
 
@@ -64,31 +64,29 @@ A merged pull-request close performs no prerelease cleanup because the default-b
 
 The alternative of never cleaning up on a close requires scheduled garbage collection and leaves abandoned prereleases available until that collection runs. This candidate selects abandoned-close cleanup instead; it does not change the existing unapproved caller contract.
 
-## Candidate concurrency isolation
+## Candidate concurrency and recovery
 
-Cancellation is conditional, not globally disabled. Only an explicit read-only mode may cancel a superseded run. A route that can mutate an external release resource never cancels and is never canceled.
+The candidate caller recommendation is:
 
-| Lifecycle route | Concurrency domain | Cancellation policy | Mutable resources |
-| --- | --- | --- | --- |
-| Explicitly read-only pull-request CI | Pull request number and read-only mode | Superseded runs may cancel | None. |
-| Prerelease evaluation and abandoned-close cleanup | Pull request number and mutation mode | Never cancel | Prerelease artifacts associated with that pull request. |
-| Default-branch push and manual recovery | Default-branch ref and mutation mode | Never cancel | Stable package, GitHub Release, tag, uploads, Pages, and promotion cleanup. |
-| Scheduled validation | Published-version read domain | May cancel only another explicit scheduled validation | None. |
+```yaml
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+```
 
-Concurrency selection occurs before the reusable workflow can produce a planner output. The candidate therefore requires either an explicit event mode at the caller boundary or separate read-only and mutation workflow domains. Caller-level label inspection is insufficient: repository settings can make a label event release-capable. Manual and scheduled runs must not share a cancellation domain that can cancel a default-branch release.
+This is a candidate, not an approved caller contract. All pull-request events for one pull request share a group and may cancel an earlier run. Push, manual-dispatch, and scheduled events serialize by ref and never cancel; a manual dispatch or schedule therefore cannot interrupt a main release.
 
-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.
-
-## Why mutation-capable runs never cancel
-
-Cancellation after an external mutation begins can leave the release lifecycle partially complete:
+Cancellation can leave only transient partial state. Every pull-request route, including prerelease publication and abandoned-close cleanup, resumes and reconciles on the next `synchronize`, `labeled`, `unlabeled`, or `closed` event:
 
-| Mutation path | Cancellation hazard |
+| External operation | Required recovery behavior |
 | --- | --- |
-| PowerShell Gallery publication | The package can publish before the GitHub Release, release-asset upload, or pull-request comment completes. |
-| Prerelease cleanup | Cleanup can delete only part of a prerelease tag and release set. |
-| Default-branch release | A main release can stop between package publication, tag or GitHub Release creation, uploads, comments, Pages deployment, and promotion cleanup. |
-| Manual or scheduled run sharing a ref | A cancellation domain keyed only by ref can interrupt a main release with a manual dispatch or scheduled validation. |
+| PowerShell Gallery publication | 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 verification strategy
 
@@ -100,7 +98,8 @@ The lifecycle contract is exercised with event payload fixtures and publication
 | Version boundary | A mismatched artifact fixture that proves publication stops. |
 | 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. |
-| Conditional cancellation | A superseded read-only CI fixture plus release-capable label, cleanup, main-push, manual, and scheduled fixtures that prove mutation-capable runs do not cancel. |
+| 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. |
+| 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
 
@@ -110,7 +109,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.
-- The exact caller triggers and concurrency expression, which remain subject to [PSModule/Process-PSModule#514](https://github.com/PSModule/Process-PSModule/issues/514).
+- 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

@@ -165,29 +165,23 @@ Scenario: Retry a publication after an interrupted run
   And it does not duplicate the package, tag, or release
 ```
 
-### NFR2 — Cancellation MUST be conditional on an explicit mutability mode {#nfr2}
+### NFR2 — Pull-request cancellation MUST preserve non-pull-request serialization {#nfr2}
 
-A run explicitly classified as read-only pull-request CI SHOULD cancel a superseded `opened`, `reopened`, or `synchronize` run for the same pull request. A run that may publish to the PowerShell Gallery, create or upload a GitHub Release or tag, deploy Pages, or clean up prereleases MUST NOT be canceled. Caller-level label inspection MUST NOT determine mutability because repository settings can change the release decision. Manual and scheduled runs sharing a ref MUST NOT cancel a default-branch release.
+All pull-request events for one pull request MUST share a cancellation scope, so a newer pull-request event cancels a superseded run. Push, manual dispatch, and scheduled runs MUST share ref-based serialization and MUST NOT cancel an in-progress run.
 
 #### Behavioral scenarios {#nfr2-scenarios}
 
 ```gherkin
-Scenario: Supersede read-only pull-request CI
-  Given an explicitly read-only pull-request CI run is in progress
-  When a newer synchronize event starts the same read-only route
-  Then the older run may be canceled
-  And no release-related resource is mutated by either run
-
-Scenario: Preserve a release-capable run
-  Given a run may publish, deploy, or clean up prereleases
-  When a newer event starts
-  Then the release-capable run is not canceled
-  And the newer event does not infer safety from pull-request labels alone
-
-Scenario: Keep main release independent from manual and scheduled runs
+Scenario: Supersede a pull-request run
+  Given a pull-request run is in progress
+  When a newer synchronize, label, unlabel, or close event starts
+  Then the older pull-request run is canceled
+
+Scenario: Serialize non-pull-request runs
   Given a default-branch release is in progress
   When a manual dispatch or scheduled validation starts for the same ref
-  Then neither event cancels the default-branch release
+  Then the later run waits for the default-branch release
+  And neither run cancels the other
 ```
 
 ### NFR3 — Each lifecycle outcome MUST be auditable {#nfr3}
@@ -205,6 +199,40 @@ Scenario: Inspect a scheduled validation result
   And it identifies that no release mutation occurred
 ```
 
+### 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.
+
+#### Behavioral scenarios {#nfr4-scenarios}
+
+```gherkin
+Scenario: Resume a canceled prerelease publication
+  Given a canceled pull-request run published a prerelease package but did not finish its release metadata
+  When a later pull-request event is processed
+  Then the workflow detects the existing version
+  And it completes or reconciles the prerelease release state without duplication
+
+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
+```
+
+### NFR5 — Pull-request events MUST NOT produce production artifacts {#nfr5}
+
+A pull-request event MUST NOT create a stable or signable production artifact. Pull-request events MAY create only eligible prerelease artifacts and their associated metadata.
+
+#### Behavioral scenarios {#nfr5-scenarios}
+
+```gherkin
+Scenario: Evaluate an eligible prerelease pull request
+  Given a pull request is eligible for prerelease publication
+  When its release-capable path completes
+  Then it creates only prerelease artifacts and metadata
+  And it does not create a stable or signable production artifact
+```
+
 ## Cross-cutting acceptance criteria
 
 ### AC1 — Verifies: [FR1](#fr1), [FR6](#fr6), [FR7](#fr7), [NFR1](#nfr1)
@@ -219,14 +247,15 @@ Scenario: Recover release notes after a missed main-push publication
   And a retry creates no duplicate publication
 ```
 
-### AC2 — Verifies: [FR2](#fr2), [FR5](#fr5), [FR6](#fr6), [NFR2](#nfr2), [NFR3](#nfr3)
+### AC2 — Verifies: [FR2](#fr2), [FR4](#fr4), [FR5](#fr5), [FR6](#fr6), [NFR2](#nfr2), [NFR3](#nfr3), [NFR4](#nfr4), [NFR5](#nfr5)
 
 ```gherkin
-Scenario: Lifecycle runs preserve release ownership
+Scenario: Lifecycle runs preserve release ownership after cancellation
   Given a scheduled validation and an abandoned pull-request cleanup overlap a main-push release
+  And the cleanup supersedes a canceled prerelease publication
   When all three runs complete
   Then the scheduled run reports validation without a release mutation
-  And the cleanup affects only the abandoned pull request's prereleases
+  And the cleanup reconciles only the abandoned pull request's prereleases
   And none of the runs cancel the main-push release
   And the main-push run is the only run that publishes the stable release and performs promotion cleanup
 ```