Make release impact and user adoption explicit in PR release notes #202

Problem

The PR Format makes the pull request the release note but does not require one ordered adoption path, an effective release decision, or a complete incremental consumer-change record. Consumers cannot reliably compose the changes across releases when required actions remain scattered through implementation notes or version-specific skills.

Evidence

The original request reports a review of 242 pull requests in PSModule/Process-PSModule: 235 had non-empty descriptions, 24 used both ending details blocks, and 60 used the current user-facing change sections. Those are the original audit's observations, not counts re-established by this delivery.

The original examples remain supporting context: PSModule/Process-PSModule#524, PSModule/Process-PSModule#529, and PSModule/Process-PSModule#531 distribute or omit adoption/version information; PSModule/Process-PSModule#535 illustrates an ordered consumer-change section.

The release-authoring work in PSModule/Process-PSModule#537 needs an artifact-neutral MSX contract to reference. MSXOrg/docs#196 independently changes release-policy resolution; this delivery reports the effective policy decision without redesigning it or taking ownership of that PR.

Request

Make a release-bound PR sufficient incremental evidence for a consumer to adopt that release, and require publication to preserve that evidence. Retain the summary, applicable user-facing change sections, and final Technical details / Relevant issues blocks. Add required Adopting this release and Release impact blocks and distinguish consumer evidence from maintainer evidence inside Technical details.

Acceptance criteria

• An author can describe a release for any artifact type using one complete example, including ordered adoption or an explicit no-action outcome.
• Change classification is based on the declared target audience's supported use and integration contracts. Users and integrators can be the same people; both Process-PSModule and PowerShell modules illustrate this. Each initiative defines its audience, and each repository states or explicitly adopts and specializes that definition in its README.
• Each affected consumer surface records its identifier, before/after behavior, applicability and prerequisites, exact action, and verification. Breaking behavior remains visible even when the version policy selects Minor, including pre-1.0 releases.
• Release impact records the effective release decision and its source, semantic effect, and release/base coordinates without inventing final versions before publication.
• An explicit owned bump label overrides an optional, valid repository-configured DefaultBump. If neither supplies a level, there is no implicit patch fallback: the decision is missing. Explicit release:skip remains a valid no-release decision.
• Missing decisions, invalid defaults, and conflicting owned labels fail a named required PR CI check before merge. Source, release-label, and settings changes re-evaluate the decision. Branch protection/rulesets require that check, so an absent, pending, or failed result cannot permit merge; release-time validation remains mandatory.
• Applicable framework releases identify a verified compatible immutable template commit, producer version/source identity, compatibility evidence, and linked template work or a justified no-change result.
• The release-management contract preserves the release-bound title and complete authored body, including adoption and technical details. Actual coordinates and provenance are finalized by the release process in a distinct envelope.
• Bundled, optional ad hoc, and source-ref-specific prerelease notes retain the same evidence obligations. Published-note corrections have an audit trail and never change artifacts, tags, SHAs, or historical behavior.
• Release-label names, SemVer arithmetic, pre-1.0 classification, and issue-reference/closure rules remain unchanged. Audience-based impact determines the type; the explicit label or configured default supplies the effective release level. The common consumer procedure, producer/template completion gates, pilot execution, and historical backfill are not implemented in this PR.

Technical decisions

• Edit src/docs/Ways-of-Working/PR-Format.md and src/docs/Capabilities/release-management/{spec,design}.md, extending their existing shape rather than reformatting unrelated requirements.
• Give audience declarations one rule in Readme-Driven-Context.md, linked from Repository-Standard.md and Organization-Standard.md. Apply it in the MSX Docs README and the PSModule initiative overview. Keep initiative-specific operational guidance producer-owned; no fleet of consumer README edits is included.
• Keep the contract in structured Markdown inside the PR body; no JSON/YAML sidecar, release-history file, migration cookbook, updater, publisher implementation, or synchronization service is added.
• Describe the delta introduced by one release. Consumers compose multiple release records; this authoring slice does not implement that traversal procedure.
• Name changed public inputs, APIs, configuration keys, paths, permissions, secret names without values, runtime/tool requirements, defaults, removals, and behavior. Changed filenames alone are insufficient.
• Report the effective release resolver decision and its source. Reuse the optional DefaultBump setting name from 📖 [Docs]: Release bumps now have a configurable default #196 in .github/release.config.yml; accept patch, minor, or major only, with no built-in fallback. Keep the existing label names and branch/type model; 📖 [Docs]: Release bumps now have a configurable default #196 still owns its separate redesign and must reconcile its conflicting implicit-patch proposal before merge.
• Align PR Format, readiness/Implement wording, Automation Labels, branching/promotion and continuous-delivery guidance, Natural Language error examples, and the VS Code framework with the shared resolver. Document the required pre-merge decision check through the existing merge-automation contract; do not add a publisher or CI implementation to this docs repository.
• Keep .github/plugin/msx/skills/msx-ways-of-working-pr-format/SKILL.md as a thin pointer. Its existing discovery wording is sufficient, so plugin metadata and versions do not change.
• Prepare the common upgrade procedure and completion gates as a separate native Task, with execution order represented by a native dependency. PSModule pilot work and historical writes remain separately refined delivery work.
• The existing repository-protection gap in MSXOrg/docs#166 prevents safe auto-merge: the active main ruleset has no required-status-check rule. Correcting governance is outside this PR; auto-merge remains disabled while that prerequisite is unresolved.

Implementation plan

• Inspect the existing issue, PR format, publication contract, thin pointer, and in-flight release-policy diff; establish authoring cases for a no-action patch, breaking transition, skipped releases, prerelease target, and non-latest target.
• Add the incremental PR evidence contract and complete artifact-neutral example in src/docs/Ways-of-Working/PR-Format.md; preserve version and issue rules.
• Compare publication requirements against the authoring cases, including full-body retention, provenance, bundled/ad hoc/prerelease mapping, and metadata-only correction.
• Align src/docs/Capabilities/release-management/spec.md and design.md with the PR evidence contract.
• Establish audience-classification cases for shared user/integrator roles, a breaking manifest or workflow edit, a mixed breaking/fix change, and missing audience context.
• Clarify audience ownership in the README/organization/repository standards and PSModule overview, then make PR classification follow supported audience impact rather than path-only inference.
• Establish decision cases for explicit level, configured default, precedence, missing/invalid/conflicting inputs, skip, prerelease, unowned labels, and CI re-evaluation that blocks merge.
• Correct the release spec/design and all directly affected authoring, gate, and consuming guidance; regenerate indexes for changed descriptions.
• Run the existing documentation index check, relative-link and applicable cross-repository-link checks, and targeted Markdown linting. Run existing documentation tests where applicable; do not introduce a validation toolchain.
• Reconcile the extended authoring cases and standards/framework alignment and repeat the scoped issue-convergence sweep. The dependent common-procedure Task remains prepared.
• Complete the current-head Copilot review loop, read its full summary including suppressed comments, and address every concern. Zero new inline comments alone is not a clean review.
• Complete the normal review handoff once the native repository-governance prerequisite is satisfied. Leave auto-merge disabled and preserve the user-selected PR readiness state while reporting unmet prerequisites.