docs: aggregate skipped stable run intent

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

Author: MariusStorhaug

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

@@ -56,11 +56,17 @@ The build stage stamps exactly the planned manifest version and prerelease ident
 
 One general module release action or reusable workflow consumes enriched Settings after validation. It handles stable release, prerelease, recovery or resume, cleanup-only, and no-op actions according to the planned desired release action and flags. It verifies the artifact when an artifact is required and reconciles only the requested state. It does not recompute versioning, labels, event routing, or cleanup policy.
 
+## Candidate stable Plan aggregation
+
+Every stable push and recovery target uses the same aggregation rule. Plan finds the last successfully published stable version and its associated target commit, then queries merged pull requests through the requested target commit. It aggregates their release intent and uses that range for the stable version decision and release notes.
+
+This aggregation is not limited to manual recovery. GitHub can replace an intermediate pending run when a newer run enters the same concurrency group, so the later stable target must carry forward every merged pull request since the last successful publication.
+
 ## Candidate manual recovery
 
-A manual recovery route accepts only a selected default-branch commit. It first determines whether a stable publication already covers that commit and returns a no-op when one exists.
+A manual recovery route accepts only a selected default-branch commit. It uses the stable Plan aggregation rule and returns a no-op when a stable publication already covers that commit.
 
-For a missing publication, the route identifies the last published stable version and its associated default-branch commit. It then queries merged pull requests targeting the default branch between that publication boundary and the selected commit. The release-note reconstruction uses that ordered, de-duplicated result rather than the manual-dispatch event payload, which has no pull-request context.
+For a missing publication, the release-note reconstruction uses the ordered, de-duplicated aggregated pull-request range rather than the manual-dispatch event payload, which has no pull-request context.
 
 The recovery route validates the selected commit using the same release gates as a default-branch push. It produces a stable release only after the artifact/version boundary succeeds. This keeps recovery notes traceable even when the normal main-push run was missed or interrupted.
 
@@ -84,7 +90,9 @@ concurrency:
   cancel-in-progress: ${{ github.event_name == 'pull_request' }}
 ```
 
-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.
+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 the full `github.ref` and do not cancel a running run. GitHub permits at most one running and one pending run per group, so a newer same-group event can replace an older pending run even when cancellation is disabled. A manual dispatch on `main` shares `refs/heads/main` with a push: it queues behind a running push but can replace an older pending main run.
+
+The candidate retains full `github.ref`. `github.ref_name` neither prevents pending-run replacement nor distinguishes branches and tags with the same name.
 
 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:
 
@@ -121,7 +129,7 @@ The lifecycle contract is exercised with event payload fixtures and publication
 | 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. |
+| Stable aggregation | Bursts of main-push, manual-dispatch, and scheduled fixtures that replace an intermediate pending run and prove the later stable target aggregates all unreleased merged pull requests. |
 
 ## Decisions requiring approval
 

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

@@ -120,7 +120,7 @@ Scenario: Abandon a pull request with prereleases
 
 ### 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 successful stable release for a merged pull request MUST own promotion cleanup.
+A push to the default branch MUST publish a stable version only after all required build, test, quality, and publication gates succeed. A successful stable release MUST own promotion cleanup.
 
 #### Behavioral scenarios {#fr6-scenarios}
 
@@ -188,6 +188,27 @@ Scenario: Execute a planned cleanup-only action
   And it does not create or publish an artifact
 ```
 
+### FR10 — Stable targets MUST aggregate unreleased merged pull requests {#fr10}
+
+For every stable push or recovery target, the plan MUST aggregate merged pull requests and their release intent from the last successfully published version through the target commit. The resulting stable action MUST converge correctly when GitHub replaces an intermediate pending run.
+
+#### Behavioral scenarios {#fr10-scenarios}
+
+```gherkin
+Scenario: Publish after an intermediate pending push is replaced
+  Given merged pull requests exist after the last successfully published version
+  And an intermediate default-branch push is replaced while pending
+  When a later default-branch push is planned
+  Then the plan aggregates every merged pull request through the later target commit
+  And the stable release uses the aggregated release intent
+
+Scenario: Recover a range of unreleased merged pull requests
+  Given merged pull requests exist after the last successfully published version
+  When a maintainer dispatches recovery for a later default-branch commit
+  Then the plan aggregates every merged pull request through that target commit
+  And the release notes use that aggregated range
+```
+
 ## Non-functional requirements
 
 ### NFR1 — Lifecycle mutations MUST be idempotent {#nfr1}
@@ -206,7 +227,7 @@ Scenario: Retry a publication after an interrupted run
 
 ### NFR2 — Pull-request cancellation MUST preserve non-pull-request serialization {#nfr2}
 
-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.
+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 a full-ref serialization scope and MUST NOT cancel an in-progress run. Because GitHub permits at most one running and one pending run per group, a newer same-group non-pull-request run MAY replace an older pending run; the stable plan MUST therefore converge from the last successfully published version.
 
 #### Behavioral scenarios {#nfr2-scenarios}
 
@@ -218,9 +239,11 @@ Scenario: Supersede a pull-request run
 
 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 the later run waits for the default-branch release
-  And neither run cancels the other
+  And an earlier default-branch run is pending
+  When a manual dispatch or scheduled validation starts for the same full ref
+  Then the later run does not cancel the running release
+  And it may replace the older pending run
+  And the next stable plan aggregates the unreleased merged pull requests
 ```
 
 ### NFR3 — Each lifecycle outcome MUST be auditable {#nfr3}
@@ -308,7 +331,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), [FR8](#fr8), [FR9](#fr9), [NFR2](#nfr2), [NFR3](#nfr3), [NFR4](#nfr4), [NFR5](#nfr5), [NFR6](#nfr6)
+### AC2 — Verifies: [FR2](#fr2), [FR4](#fr4), [FR5](#fr5), [FR6](#fr6), [FR8](#fr8), [FR9](#fr9), [FR10](#fr10), [NFR2](#nfr2), [NFR3](#nfr3), [NFR4](#nfr4), [NFR5](#nfr5), [NFR6](#nfr6)
 
 ```gherkin
 Scenario: Lifecycle runs preserve release ownership after cancellation