Release authors can write self-contained upgrade notes

.github/plugin/README.md

@@ -38,6 +38,11 @@ The
 [`psmodule-skill-authoring`](./psmodule/skills/psmodule-skill-authoring/SKILL.md)
 skill keeps plugin skills thin and points shared authoring guidance to the
 documentation site.
+The
+[`psmodule-release-note-authoring`](./psmodule/skills/psmodule-release-note-authoring/SKILL.md)
+skill formats pull request titles, descriptions, and labels as user-facing
+release records with complete upgrade instructions, verified semantic impact,
+and publisher-resolved versions.
 Verify the installation with:
 
 ```console

.github/plugin/psmodule/skills/psmodule-release-note-authoring/SKILL.md

@@ -0,0 +1,21 @@
+---
+name: psmodule-release-note-authoring
+description: Author or review pull requests as complete consumer upgrade records using the shared release-note guidance.
+---
+
+# Format release-note pull requests
+
+Use when formatting, rewriting, or reviewing a pull request whose title and complete description become release
+notes. First read the [authoring guide](../../../../../docs/content/guides/formatting-release-note-prs.md);
+it owns the release-record content, replay check, evergreen-documentation boundary, and validation.
+The linked [MSX PR format](https://msx.no/docs/Ways-of-Working/PR-Format/) owns the shared title and description structure.
+
+If the repository-relative guide is unavailable from an installed plugin, read its
+[published page](https://psmodule.io/docs/guides/formatting-release-note-prs/) instead.
+
+## Agent-specific contract
+
+- Read the target repository's instructions and linked evergreen documentation before editing PR metadata.
+- Apply the guide's authoring and replay checks to the full delivered range.
+- Report the edited PR URL, relevant baseline, verified impact, and validation outcomes to the owning session.
+- Stop and report when the cited guidance or required source evidence is unavailable; identify the evidence gap.

.github/plugin/psmodule/skills/psmodule-v8-upgrade/SKILL.md

@@ -67,7 +67,6 @@ The current template's default repository anatomy is:
 │   │   ├── .powershell-psscriptanalyzer.psd1
 │   │   └── .textlintrc
 │   ├── PSModule.yml
-│   ├── pull_request_template.md
 │   ├── release.yml
 │   ├── workflows/
 │       └── Process-PSModule.yml
@@ -107,7 +106,7 @@ Treat files and directories as follows:
   Preserve its intent and only migrate paths when the framework contract
   requires it.
 - `.github/PSModule.yml`, linters, Dependabot, CODEOWNERS, release metadata,
-  pull-request templates, and repository guidance are configuration surfaces.
+  and repository guidance are configuration surfaces.
   Inspect and preserve them independently of the caller workflow.
 - `tests/BeforeAll.ps1` and `tests/AfterAll.ps1` are optional root-level
   module-local phases, not recursively discovered test files.

docs/content/guides/configuring-the-pipeline.md

@@ -142,16 +142,29 @@ Publish:
     UsePRTitleAsNotesHeading: true
 ```
 
-This produces release notes like:
+This produces release notes like this illustrative excerpt:
 
 ```markdown
-# 🚀 Add new authentication feature (#42)
+# Commands identify missing required settings (#42)
 
-This PR adds OAuth2 support with the following changes:
-- Added `Connect-OAuth2` function
-- Updated documentation
+Commands identify a missing required setting in the error message so users can correct the configuration directly.
+Accepted configuration and invocation stay unchanged.
+
+<!-- ANNOUNCEMENT STOP -->
+
+## Fixed: Missing settings are easier to identify
+
+A missing required setting is named in the error instead of producing an unspecified configuration error. This affects
+users diagnosing invalid configuration. No configuration, code, or invocation change is required beyond selecting
+this release. Run the existing configuration check to verify that valid configuration still succeeds and an omitted
+required setting is named in the error.
 ```
 
+Use [Formatting release-note pull requests](formatting-release-note-prs.md) for the complete structure, including
+result-scoped upgrade instructions and evidence. The author describes verified semantic impact and the applicable
+baseline; the publisher resolves the version. Keep complete transition instructions in the published body so PR and
+diff links remain optional depth.
+
 ### Version-only release names
 
 If you prefer version numbers as release names but still want PR-based notes:

docs/content/guides/formatting-release-note-prs.md

@@ -0,0 +1,160 @@
+---
+title: Formatting release-note pull requests
+description: Author complete release records that consumers can replay for upgrade instructions while resource documentation stays evergreen.
+---
+
+# Formatting release-note pull requests
+
+The release-bound pull request title and complete description are the authored release record. Write them so consumers
+can understand what changes, why it changes, how it affects them, and exactly what to do when upgrading. Published
+release notes are sufficient for that decision; the pull request and commit diffs provide optional deeper evidence.
+
+With the default Process-PSModule settings, automation reuses the pull request title as the release notes heading and
+the description as the release notes body. The release name is the resolved version unless
+`Publish.Module.UsePRTitleAsReleaseName` changes that setting. This guide governs authoring; it does not change the
+publisher, version resolver, label mappings, or release-note settings.
+
+Use the [MSX PR format](https://msx.no/docs/Ways-of-Working/PR-Format/) for titles and description structure.
+Write the record directly in the pull request using its in-document examples. The guidance applies to PowerShell
+modules, reusable workflows, GitHub Actions, libraries, services, infrastructure modules, and published guidance.
+
+## Release records and evergreen documentation
+
+Each release records its incremental change from a declared release/source baseline. Consumers compose the applicable
+records after their current baseline through their selected target. The newest note does not replace intervening
+instructions, and an individual note does not need a migration manual from every historical version.
+When later instructions supersede earlier edits, explain which actions remain for the target and preserve any
+explicitly required intermediate installation or run.
+
+| Surface | Content it owns |
+| --- | --- |
+| Published release record | Delivered changes, rationale, affected consumers, old-to-new transitions, exact adoption or migration actions, prerequisites, ordering, and verification. |
+| Product or resource documentation | Supported current-state behavior, inputs, outputs, configuration, and usage examples. |
+| Pull request and commit diffs | Optional implementation depth and supporting evidence beyond the complete published instructions. |
+
+Keep necessary before-and-after examples in the release record. Keep current supported examples in resource
+documentation, without migration history or instructions tied to an earlier release. Preserve legitimate decision and
+research records in their established homes. Do not introduce a standalone changelog or version-specific migration-guide
+hierarchy as a second upgrade history.
+
+Missing applicable instructions are an evidence gap to resolve with the producer, not an expectation that consumers
+reconstruct the upgrade from pull requests, diffs, or today's resource documentation.
+
+## Before starting
+
+- Identify the artifact, its supported consumers, and every affected public interface.
+- Inspect the complete base-to-head diff and the full delivered range from the declared release/source baseline.
+  Include prior merged or skipped deltas that now enter the artifact, not only the latest PR or bundled change.
+- Establish the release/source baseline for the consumer delta from published records and immutable source evidence.
+  Distinguish it from the version-computation base when they differ; state explicitly when there is no prior release.
+- Inspect the publishing route and effective version-label settings. Verify semantic impact independently of the label
+  name or default, and identify every applicable consumer action or verified no-action result.
+
+## Steps
+
+1. Write a short, audience-first outcome as the title, without an icon or type prefix.
+2. Open with concise prose explaining the result, rationale, affected consumers, and required action. Lead with breaking
+   impact when applicable. End the shareable summary with `<!-- ANNOUNCEMENT STOP -->`.
+3. Group results in the shared order: `Breaking`, `Removed`, `New`, `Changed`, then `Fixed`. Use
+   `## <classifier>: <result>`, omit empty groups, and explain each result before any example or table.
+4. Put complete adoption or migration instructions in each result's reader-facing prose before its evidence blocks.
+   Include exact transition examples when needed. Coordinate dependent actions in one ordered sequence within the
+   record rather than maintaining competing instructions.
+5. Keep implementation and validation evidence in the result's `Technical details`, with `Related references` scoped to
+   that same result. References supplement the published instructions; they never replace required steps.
+6. Include the conditional release-decision block only when the target route invokes Release Management. Describe
+   verified semantic impact and its configured source, not a predicted final version; see
+   [Release decisions and coordinates](#release-decisions-and-coordinates).
+7. Update the relevant resource documentation to the supported current state. Remove authoring placeholders, empty
+   scaffolding, and comments other than the shareable-summary marker.
+
+## Writing an incremental upgrade record
+
+Give every affected consumer a complete answer, including routine dependency, reference, configuration, or command
+changes. Adoption and migration instructions are not limited to data or platform migrations.
+
+| Information | What the record must answer |
+| --- | --- |
+| Baseline and applicability | Which prior release/source the delta starts from, who is affected, and which starting conditions or prerequisites matter. |
+| Change, rationale, and impact | What changes, why it changes, and how supported consumers experience it. State breaking behavior independently of its SemVer classification. |
+| Exact actions | Which public commands, configuration keys, defaults, inputs, outputs, permissions, secret names, runtimes, or references change. Include exact edits and necessary before-and-after examples; never include secret values. |
+| Order and intermediate steps | Which edits, installations, runs, or deployments depend on others. Require an intermediate version only when the transition actually needs one. |
+| Verification | Which observable result or existing check confirms that the consumer is aligned. |
+| No-action result | Explicitly state when no configuration, code, or invocation change is required beyond selecting the release. Distinguish optional feature adoption from required changes. |
+| Integration template | When applicable, identify the template repository and verified compatible immutable commit, producer-source compatibility evidence, and linked template work or a justified no-change result. |
+
+If no integration template applies, explain why rather than inventing one. Do not substitute a moving template branch
+or today's documentation for evidence about the released contract.
+
+## Release decisions and coordinates
+
+The [MSX PR format](https://msx.no/docs/Ways-of-Working/PR-Format/) owns the conditional `Release decisions` block.
+Include it only when the target route invokes Release Management; inspect the caller and effective configuration
+rather than inferring invocation from a settings file. Otherwise omit it and still explain the adoption or no-action
+outcome in the result prose.
+
+For the existing Process-PSModule resolver, inspect `Publish.Module.MajorLabels`, `MinorLabels`, `PatchLabels`,
+`IgnoreLabels`, and `AutoPatching` in the effective [settings](../reference/settings.md). Preserve the configured
+label names and defaults; this authoring guidance does not adopt another publisher's label namespace or configuration.
+Describe the selected semantic effect and stable/prerelease mode. For a skip decision, state that no artifact is
+published and no version transition occurs.
+
+Authors state verified impact and the known consumer-change baseline. The publishing process resolves the final
+numeric version and release identity from its actual version base. Do not calculate a planned release version or name
+in the PR body. A known source baseline is evidence, not a prediction of publication coordinates.
+
+## Replay an illustrative release range
+
+This walkthrough reuses the timeout-setting example from the shared PR format. It illustrates already published
+records, not Process-PSModule release history or changes to its settings. The version numbers below represent resolved
+publication identities, not numbers assigned by a PR author. This example product has no integration template.
+
+### Published v2.0.0 - Explicit timeout units
+
+**Baseline:** `v1.4.2`. **Impact:** breaking, Major. The optional job configuration key `timeout` becomes
+`timeoutSeconds` so its units are explicit. The positive integer value, seconds unit, and 30-second default remain
+unchanged. Configurations using `timeout` are rejected; configurations that omit it need no edit.
+The job invocation and all other settings remain unchanged.
+
+1. If the configuration contains `timeout: 20`, replace it with `timeoutSeconds: 20`, preserving the value. Do not
+   supply both keys. If the key is absent, keep it absent to retain the 30-second default.
+2. Apply that configuration edit together with the selected target version, not to the previous version. No data
+   conversion, intermediate installation, or intermediate run is required.
+3. Verify with the unchanged job invocation against the selected version: `timeoutSeconds: 20` is accepted and
+   `timeout: 20` is rejected. A job exceeding its timeout must be canceled at the configured limit, or 30 seconds
+   when omitted.
+
+### Published v2.0.1 - Clearer timeout validation errors
+
+**Baseline:** `v2.0.0`. **Impact:** compatible Patch. Invalid timeout values report the accepted positive-integer
+range, making configuration errors easier to correct. Accepted configuration, units, defaults, and invocation stay
+unchanged. No configuration, code, or invocation change is required beyond selecting this release. Run the existing
+job invocation to verify the same configuration acceptance and timeout cancellation behavior.
+
+A consumer moving from `v1.4.2` to `v2.0.1` reads both records in order, applies the applicable key rename, selects
+`v2.0.1` directly, and runs the stated checks. A consumer starting at `v2.0.0` reads only the patch record and needs no
+configuration edit. Reading every applicable record does not require installing every intermediate version.
+
+The resource documentation for this example describes only the optional positive-integer `timeoutSeconds` setting,
+its seconds unit, 30-second default, and current usage. The release records carry the removed key, transition
+instructions, and reasons for each change.
+
+## Verify
+
+- The complete published record explains what changed, why, impact, applicability, exact actions, and verification,
+  or a verified no-action result.
+- A consumer can compose all applicable records from an identified baseline through a selected target without
+  consulting PRs, diffs, or historical versions of resource documentation for missing instructions.
+- The summary marker, classifiers, scoped blocks, and conditional release metadata follow the shared format.
+- Semantic impact and any reported label/default agree with the effective route; no final numeric version is predicted.
+- Resource documentation contains the supported current state, and release records contain migration history.
+- No placeholders, secret values, empty scaffolding, or authoring comments remain in the finalized record.
+
+## If it fails
+
+| Symptom | Cause | Resolution |
+| --- | --- | --- |
+| The final version is unknown before publication. | The publisher has not resolved its actual base. | State verified semantic impact and the known change baseline; leave numeric coordinates to the publisher. |
+| A consumer cannot determine an applicable upgrade step. | The release record is incomplete or its baseline is unverified. | Report the evidence gap and complete the record from verified source evidence; do not infer no action or require consumers to mine diffs. |
+| The newest note omits an earlier breaking transition. | The consumer read only the target note. | Compose every applicable release record after the current baseline through the target, in order. |
+| Resource documentation contains an old-to-new walkthrough. | Release history was mixed with current usage. | Keep the required transition in the release record and the supported current example in resource documentation. |

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

@@ -9,6 +9,24 @@ Process-PSModule orchestrates the module lifecycle through GitHub Actions. Versi
 requests and resolved once, in the Plan stage, before anything is built. Stable publication occurs only from a push to
 the configured default branch.
 
+With the default release-note settings, the pull request title becomes the release notes heading and its description
+becomes the release notes body. The release name remains the resolved version by default. Authors state verified
+semantic impact and applicable source baselines; the publisher resolves final numeric coordinates. See
+[Formatting release-note pull requests](formatting-release-note-prs.md) for the complete authoring contract.
+
+## Using release notes for an upgrade
+
+Identify the consumer's current release/source baseline and selected target, then read every applicable published
+release record after that baseline through the target in order. Compose the stated prerequisites, adoption or
+migration actions, and verification for the consumer's starting state. Reading the intervening records does not
+require installing or running every intermediate version; do so only when a record explicitly requires it.
+Apply later supersession instructions while preserving any required intermediate operations.
+
+The notes provide the complete change, rationale, impact, and action or explicit no-action result. Pull requests and
+commit diffs provide optional depth. Missing required instructions are an evidence gap to resolve with the producer.
+Product and resource documentation describes supported current-state behavior and usage; release records own
+historical transitions. See the [illustrative replay](formatting-release-note-prs.md#replay-an-illustrative-release-range).
+
 ## Flow
 
 1. Resolve settings and release intent.

docs/content/index.md

@@ -43,6 +43,7 @@ Task-oriented deep dives into the pipeline's functionality.
 | [PSModule process marketplace](https://github.com/PSModule/Process-PSModule/tree/main/.github/plugin) | Register the initiative marketplace and install the PSModule process plugin. |
 | [Skipping framework tests](guides/skipping-framework-tests.md) | Skip individual framework tests on a per-file basis. |
 | [Versioning and releases](guides/versioning-and-releases.md) | Label-driven versioning, prereleases, and what a release produces. |
+| [Formatting release-note pull requests](guides/formatting-release-note-prs.md) | Author complete release records for consumer upgrades while resource documentation stays evergreen. |
 | [Validating before review](guides/validating-before-review.md) | The PSModule validation pass before a draft pull request is marked ready. |
 | [Writing plugin skills](guides/writing-plugin-skills.md) | Author and maintain thin plugin skills that point to shared documentation. |
 | [Module development orchestration](guides/module-development-orchestration.md) | Coordinate substantial work across an orchestrator session and narrowly scoped child sessions. |