docs: refine lifecycle concurrency candidate

Co-authored-by: Copilot App <[email protected]>

Author: MariusStorhaug

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

@@ -19,18 +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 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.
 
-| Event | Candidate route | Mutation class | Required result |
-| --- | --- | --- | --- |
-| `workflow_dispatch` on the default branch | Recovery release | Stable release or explicit no-op | Rebuild and validate the selected commit; reconstruct the unreleased release notes. |
-| `schedule` | Published-artifact validation | Validation only | Validate the latest published stable artifact and its documentation. |
-| Pull request `opened`, `reopened`, `synchronize` | Pull-request CI | Validation only | Report configured validation on the pull request. |
-| Pull request `labeled`, `unlabeled` | Prerelease evaluation | Prerelease or validation only | Re-evaluate the full label set and publish only an eligible prerelease. |
-| Pull request `closed` | Pull-request cleanup | Prerelease cleanup only | Remove only prereleases owned by the closed pull request. |
-| Push to the default branch | Stable release | Stable release | Resolve merged-pull-request intent when applicable, then publish after required gates. |
+| Event | Candidate route | Mutability mode | 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. |
+| 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, 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, 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.
 
 ## Candidate artifact and version boundary
 
@@ -57,29 +58,49 @@ The recovery route validates the selected commit using the same release gates as
 
 The scheduled route resolves the latest published stable version as an input, not as a version to create. It validates the downloaded package and its published documentation with the checks appropriate to a published consumer artifact. Its plan record sets the mutation class to validation only, so publication and cleanup stages cannot run.
 
+## Candidate close behavior
+
+A merged pull-request close performs no prerelease cleanup because the default-branch push is the release authority. After its stable release succeeds, that main-push route owns promotion cleanup. An abandoned pull-request close runs only pull-request-scoped prerelease cleanup because no main push will occur.
+
+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
 
-Closed-pull-request cleanup and default-branch publication use independent concurrency identities:
+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.
+
+| 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. |
+
+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.
+
+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.
 
-| Lifecycle route | Concurrency scope | Mutable resources |
-| --- | --- | --- |
-| Closed pull request | Pull request number | Prereleases associated with that pull request. |
-| Default-branch push or manual recovery | Default-branch ref | The stable release and its versioned artifacts. |
-| Scheduled validation | Published-version read scope | No release-related mutable resources. |
+## Why mutation-capable runs never cancel
 
-The routes do not cancel one another. 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 closed-pull-request route.
+Cancellation after an external mutation begins can leave the release lifecycle partially complete:
+
+| Mutation path | Cancellation hazard |
+| --- | --- |
+| 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. |
 
 ## Candidate verification strategy
 
 The lifecycle contract is exercised with event payload fixtures and publication fakes before credentials are used:
 
 | Candidate behavior | Verification |
 | --- | --- |
-| Event routing | One fixture for each supported event and pull-request activity. |
+| Event routing | One fixture for each supported event and pull-request activity, including merged and abandoned close outcomes. |
 | 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. |
-| Concurrency isolation | Overlapping closed-pull-request and default-branch-push runs that prove neither run cancels or broadens the other's scope. |
+| 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. |
 
 ## Decisions requiring approval
 
@@ -88,7 +109,7 @@ The candidate does not decide the following:
 - Whether a recovery release always uses the normal next patch version or permits an explicit version input.
 - 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 cleanup to pull-request closure.
+- 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).
 
 ## Related

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

@@ -98,23 +98,29 @@ Scenario: Remove prerelease eligibility
   And it does not create a new prerelease version
 ```
 
-### FR5 — Closed pull requests MUST clean up only their prereleases {#fr5}
+### FR5 — Closed pull requests MUST route cleanup by close outcome {#fr5}
 
-A closed pull request MUST clean up only prerelease artifacts associated with that pull request when cleanup is enabled. It MUST NOT authorize or create a stable publication.
+A merged pull request close MUST NOT perform prerelease cleanup. A successful default-branch release for the merge MUST own promotion cleanup. An abandoned pull request close MUST run cleanup-only behavior for prerelease artifacts associated with that pull request when cleanup is enabled. Neither close outcome MUST authorize or create a stable publication.
 
 #### Behavioral scenarios {#fr5-scenarios}
 
 ```gherkin
-Scenario: Close a pull request with prereleases
-  Given a closed pull request owns prerelease artifacts
-  When the cleanup workflow completes
-  Then the pull request's prerelease artifacts are removed according to configuration
+Scenario: Merge a pull request with prereleases
+  Given a merged pull request owns prerelease artifacts
+  When its close event is processed
+  Then the close event does not clean up prerelease artifacts
+  And the successful default-branch release owns promotion cleanup
+
+Scenario: Abandon a pull request with prereleases
+  Given an unmerged closed pull request owns prerelease artifacts
+  When its close event is processed
+  Then the workflow runs cleanup only for that pull request's prerelease artifacts
   And no stable artifact, tag, or release is created
 ```
 
 ### FR6 — Default-branch pushes MUST authorize stable publication after validation {#fr6}
 
-A push to the default branch MUST publish a stable version only after all required build, test, quality, and publication gates succeed. When the pushed commit is the merge commit of a pull request, the stable-release decision MUST use that pull request's release intent.
+A push to the default branch MUST publish a stable version only after all required build, test, quality, and publication gates succeed. When the pushed commit is the merge commit of a pull request, the stable-release decision MUST use that pull request's release intent. A successful stable release for a merged pull request MUST own promotion cleanup.
 
 #### Behavioral scenarios {#fr6-scenarios}
 
@@ -125,6 +131,7 @@ Scenario: Publish a merged pull request
   When all required validation gates succeed
   Then the workflow publishes the resulting stable version
   And the publication is associated with the pushed commit
+  And the successful release performs promotion cleanup
 ```
 
 ### FR7 — Published artifacts MUST match the resolved version {#fr7}
@@ -158,19 +165,29 @@ Scenario: Retry a publication after an interrupted run
   And it does not duplicate the package, tag, or release
 ```
 
-### NFR2 — Closed-pull-request cleanup and default-branch publication MUST be isolated {#nfr2}
+### NFR2 — Cancellation MUST be conditional on an explicit mutability mode {#nfr2}
 
-A closed-pull-request cleanup and a default-branch push MUST use distinct concurrency identities and MUST NOT cancel each other. Cleanup MUST remain limited to its pull request's prerelease artifacts while a default-branch push publishes a stable version.
+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.
 
 #### Behavioral scenarios {#nfr2-scenarios}
 
 ```gherkin
-Scenario: Cleanup and stable publication overlap
-  Given a pull request closes while another pull request is pushed to the default branch
-  When both workflow runs start
-  Then neither run cancels the other
-  And cleanup does not remove artifacts outside the closed pull request
-  And stable publication completes independently
+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
+  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
 ```
 
 ### NFR3 — Each lifecycle outcome MUST be auditable {#nfr3}
@@ -202,15 +219,16 @@ Scenario: Recover release notes after a missed main-push publication
   And a retry creates no duplicate publication
 ```
 
-### AC2 — Verifies: [FR2](#fr2), [FR5](#fr5), [NFR2](#nfr2), [NFR3](#nfr3)
+### AC2 — Verifies: [FR2](#fr2), [FR5](#fr5), [FR6](#fr6), [NFR2](#nfr2), [NFR3](#nfr3)
 
 ```gherkin
-Scenario: Non-stable lifecycle events remain non-mutating
-  Given a scheduled validation and a closed-pull-request cleanup overlap a main-push release
+Scenario: Lifecycle runs preserve release ownership
+  Given a scheduled validation and an abandoned pull-request cleanup overlap a main-push release
   When all three runs complete
   Then the scheduled run reports validation without a release mutation
-  And the cleanup affects only the closed pull request's prereleases
-  And the main-push run is the only run that can publish the stable release
+  And the cleanup affects 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
 ```
 
 ## Impact