diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md
index 959ba7b..43de0c3 100644
--- a/.github/CONTRIBUTING.md
+++ b/.github/CONTRIBUTING.md
@@ -2,7 +2,9 @@
Every change lands through a pull request — nothing goes directly to `main`. See the
[Contribution Workflow](https://msxorg.github.io/docs/Ways-of-Working/Contribution-Workflow/)
-for the full process: draft first, the Copilot review loop, then human review.
+for the full process: draft first, the Copilot review loop, then human review. Write the
+title and description according to
+[PR Format](https://msxorg.github.io/docs/Ways-of-Working/PR-Format/).
Everything here is a work in progress and can be improved. Fix a small problem when it is
directly in scope; register a larger or unrelated one as an issue in the repository that
@@ -50,6 +52,17 @@ owns it.
7. Open the pull request as a draft and follow the
[Contribution Workflow](https://msxorg.github.io/docs/Ways-of-Working/Contribution-Workflow/).
+## Pull request template
+
+This repository intentionally has no local pull request template. GitHub inherits
+the [MSX organization
+template](https://github.com/MSXOrg/.github/blob/main/.github/pull_request_template.md)
+from the special `MSXOrg/.github` repository. Treat that template as a starting
+scaffold; the canonical [PR
+Format](https://msxorg.github.io/docs/Ways-of-Working/PR-Format/) controls the
+final title and description. Start from its
+[complete description template](https://msxorg.github.io/docs/Ways-of-Working/PR-Format/#copy-the-complete-template).
+
## Authoring conventions
The docs are built for recursive navigation, so a reader or an agent can start at the top
@@ -113,6 +126,6 @@ conventional-commit prefixes. See
Push every commit, so the remote branch, CI, and the draft pull request always reflect the
current state of the work.
-See the [README](README.md) for what this repository is and how it is laid out, and the
+See the [README](../README.md) for what this repository is and how it is laid out, and the
[Ways of Working](https://msxorg.github.io/docs/Ways-of-Working/) for the conventions every
pull request follows — issue format, PR format, branching, and review etiquette.
diff --git a/src/docs/Capabilities/dependency-updates/design.md b/src/docs/Capabilities/dependency-updates/design.md
index 56f4797..d0dcbeb 100644
--- a/src/docs/Capabilities/dependency-updates/design.md
+++ b/src/docs/Capabilities/dependency-updates/design.md
@@ -80,14 +80,16 @@ flowchart TD
pr --> ci["Required checks run
(same gate as any PR)"]
ci --> review["Review and merge"]
review --> merged["Merged"]
- merged --> release["Separate release decision
see Release Management"]
+ merged --> release["Conditional release decision
see Release Management"]
```
### Release decision
-Dependency changes are collected before the repository release decision is
-made. The repository-wide effect follows [Release
-Management](../release-management/design.md).
+Dependency changes are collected before any repository release decision is
+made. When the target route invokes [Release
+Management](../release-management/design.md), that capability resolves the
+repository-wide effect. Otherwise the pull request omits the `Release decisions`
+block and all `release:*` labels.
## Review and merge
@@ -97,8 +99,8 @@ gates. Automatic merge, where configured, never bypasses those gates.
## Security updates
Raised on advisory disclosure, independently of the schedule, and
-**prioritised**. They otherwise follow the same review policy and release path as
-any other update.
+**prioritised**. They otherwise follow the same review policy and any applicable
+release path as another update.
## Configuration surface
@@ -108,7 +110,7 @@ any other update.
| Unsupported ecosystems | Central exception register | Centrally managed shared mechanism |
| Schedule (`interval`, `day` and `time`, or `cronjob`) and `timezone` | `.github/dependabot.yml` | Organization configuration |
| Cooldown | Updater default (three days); explicit mapping only for a deliberate non-default duration | Organization configuration |
-| Release decision | Release Management | Decided for the collected repository change |
+| Release decision | Release Management, when invoked for the target route | Decided for the collected repository change |
| Merge policy | Branch protection and merge automation | Organization configuration |
| Security updates | Repository security settings | On by default |
@@ -121,6 +123,6 @@ rather than overwrite.
- [Spec](spec.md) — the requirements this design delivers.
- [Repository Governance](../repository-governance/design.md#drift-detection-and-reconciliation) — the reconciliation that compares generated configuration against what is committed.
-- [Release Management](../release-management/design.md) — the release an update PR cuts.
+- [Release Management](../release-management/design.md) — the conditional release decision and output for an update pull request.
- [Downstream Release Propagation](../downstream-release-propagation/design.md) — the internal counterpart; propagation PRs are dependency updates too.
- [GitHub Actions](../../Coding-Standards/GitHub-Actions.md#keep-pinned-actions-current) — the Action-pin specifics this builds on.
diff --git a/src/docs/Capabilities/dependency-updates/spec.md b/src/docs/Capabilities/dependency-updates/spec.md
index 419d833..e4425b0 100644
--- a/src/docs/Capabilities/dependency-updates/spec.md
+++ b/src/docs/Capabilities/dependency-updates/spec.md
@@ -11,15 +11,18 @@ Every repository pins dependencies by version — Action SHAs, image digests,
package versions, provider constraints. Those pins age: a newer version fixes a
bug the repository still carries, and a disclosed advisory turns a safe pin into
a vulnerability. Keeping them current MUST be automatic and driven on the GitHub
-platform, producing ordinary pull requests that are reviewed and released
-through the same gate as any change — never a side channel that bypasses review.
+platform, producing ordinary pull requests that are reviewed through the same
+gate as any change — never a side channel that bypasses review. When the target
+route invokes Release Management, its release decision and publication path are
+resolved separately from the updater; a route without that invocation carries
+no `release:*` metadata.
### Principles
This capability rests on the [Principles](../../Ways-of-Working/Principles/index.md):
- **[Everything as Code](../../Ways-of-Working/Principles/Engineering-Practices.md#everything-as-code).** What is checked and how often is version-controlled configuration, not a manual audit.
-- **[Decision before change](../../Ways-of-Working/Principles/AI-First-Development.md#decision-before-change).** Every update is a pull request; its review gate approves the bump, while its release impact is decided separately.
+- **[Decision before change](../../Ways-of-Working/Principles/AI-First-Development.md#decision-before-change).** Every update is a pull request; its review gate approves the dependency change, while any applicable release decision is resolved separately.
- **[Least-privilege](../../Ways-of-Working/Principles/Purpose-and-Direction.md#least-privilege).** The updater and any auto-merge automation carry only the permissions they need.
- **[Extensible by default](../../Ways-of-Working/Principles/Software-Design.md#extensible-by-default).** Adding a package ecosystem is a configuration entry, not new machinery.
@@ -31,9 +34,9 @@ other ecosystem the repository actually uses. Two questions are asked of every p
**currency** (is a newer version available?) and **security** (does the pinned
version carry a known advisory?).
-Out of scope: what an update *does* to the artifact. That is the release the update
-produces, and it is governed by [Release
-Management](../release-management/spec.md).
+Out of scope: what an update *does* to the artifact. Where the target route
+invokes [Release Management](../release-management/spec.md), that capability
+governs the release decision and output.
## Requirements
@@ -69,7 +72,7 @@ Management](../release-management/spec.md).
### Review and release
- **FR10 — One reviewed pull request per update.** Each dependency update is a pull request that passes the full check suite before merge. Nothing is applied unreviewed, and no update takes a side channel around the gate.
-- **FR11 — Release impact is decided separately.** The dependency updater MUST NOT choose the repository's release bump. After dependency changes are collected, the repository-wide effect is decided according to [Release Management](../release-management/spec.md).
+- **FR11 — Release decisions stay independent.** The dependency updater MUST NOT choose the repository's release bump or apply `release:*` labels. After dependency changes are collected, the repository-wide effect is decided according to [Release Management](../release-management/spec.md) only when the target route invokes it.
- **FR12 — Review and merge follow the repository gate.** An update MUST pass the repository's normal review and required-check policy before merge.
- **FR13 — Automatic merge is never a bypass.** Where automatic merge is configured, it MUST preserve review requirements and required checks.
@@ -83,12 +86,12 @@ Management](../release-management/spec.md).
- An outdated or vulnerable pin produces a pull request with no human trigger.
- An ecosystem added to a repository without a corresponding updater entry is a detectable finding, not a silent gap.
-- The repository-wide release impact of dependency changes is decided separately under Release Management.
+- When the target route invokes Release Management, the repository-wide release decision for dependency changes is resolved separately under that capability.
- No dependency pull request merges without passing the same checks as any other pull request.
## Where this connects
- [Design](design.md) — the updater, review, and automatic-merge policy.
-- [Release Management](../release-management/spec.md) — the separate repository-wide release decision for merged dependency changes.
+- [Release Management](../release-management/spec.md) — the conditional, separate repository-wide release decision for merged dependency changes.
- [Repository Governance](../repository-governance/spec.md) — the reconciliation that detects an uncovered ecosystem.
- [GitHub Actions](../../Coding-Standards/GitHub-Actions.md#keep-pinned-actions-current) — keeping pinned Actions current.
diff --git a/src/docs/Capabilities/merge-automation/design.md b/src/docs/Capabilities/merge-automation/design.md
index 72abac7..9d30134 100644
--- a/src/docs/Capabilities/merge-automation/design.md
+++ b/src/docs/Capabilities/merge-automation/design.md
@@ -103,5 +103,5 @@ approval to the eligible set the ruleset actually lets it satisfy.
- [Spec](spec.md) — the requirements this design delivers.
- [GitHub Actions](../../Coding-Standards/GitHub-Actions.md#gate-merges-with-a-named-status-check) — authoring the named checks this consumes.
- [Dependency Updates](../dependency-updates/design.md) — the auto-merge policy this generalises; dependency update PRs are the canonical eligible set.
-- [Release Management](../release-management/design.md) — the release a merge triggers.
+- [Release Management](../release-management/design.md) — the release a merge triggers on an invoked route.
- [Branching and Merging](../../Ways-of-Working/Branching-and-Merging.md) — pull-request-only integration and readable history.
diff --git a/src/docs/Capabilities/release-management/design.md b/src/docs/Capabilities/release-management/design.md
index ff0a24f..fa37c86 100644
--- a/src/docs/Capabilities/release-management/design.md
+++ b/src/docs/Capabilities/release-management/design.md
@@ -1,14 +1,42 @@
---
title: Design
-description: How release management is built — a shared reusable workflow that resolves an explicit or configured SemVer bump, builds once, and publishes.
+description: How release management is built — effective defaults, owned overrides, source-bound notes, and build-once publication.
---
# Release Management — Design
-The behaviour in the [spec](spec.md) is delivered by a **shared reusable release
-workflow**. A repository opts in with a short caller workflow and a small
-`.github/release.config.yml`. The workflow supplies the shared mechanics; an
-explicit label or an intentionally configured default supplies the release level.
+The behavior in the [spec](spec.md) is delivered by shared release mechanics,
+through a reusable workflow or a native producer pipeline. A repository's
+effective release pipeline establishes which target routes are managed. The
+optional `.github/release.config.yml` file refines those settings; it does not
+create a release pipeline, and its absence does not opt a managed route out.
+Documented defaults make a managed route usable without per-PR bump labels;
+repository settings, supported caller inputs, and owned labels provide overrides.
+
+## Applicability
+
+Inspect the effective pipeline for the pull request's target route before
+reading release settings or labels. A managed route produces a versioned,
+immutable output that another system consumes by version.
+
+- When a shared workflow or native producer pipeline delivers that release
+ behavior, evaluate its release decision and require the pre-merge check. This
+ remains true when `.github/release.config.yml` is absent or the route does not
+ call a named shared workflow.
+- When the route has no versioned release behavior, Release Management does not
+ apply. Omit the `Release decisions` block and every `release:*` label,
+ including `release:skip`. A site deployment without a versioned artifact is
+ not by itself a release-managed route.
+
+Configuration can change branch types, paths, a default bump, and other release
+behavior only after the effective pipeline establishes that the route is managed.
+
+Inspect the immutable producer revision's actual settings and label mapping.
+Legacy or differing interfaces require a verified adapter or producer/configuration
+migration before the canonical signals are used. Keep exact adoption instructions
+in that producer's PR/release record. A missing mapping blocks finalization and
+decision validation; it does not opt the route out or turn an ignored signal into
+a successful skip.
## Branching model
@@ -71,69 +99,115 @@ Two consequences follow, and they are the point of the model:
## Version computation
-For PR-driven releases, the shared resolver reads the owned labels and optional
-`DefaultBump` in `.github/release.config.yml`. The setting accepts `patch`,
-`minor`, or `major`; omitting it does not supply a level. For example, this
-configuration explicitly chooses patch releases when no bump label is provided:
+For PR-driven releases on a managed route, the shared resolver reads the owned
+labels and effective settings. It records the chosen bump, mode, and the input
+that supplied each decision before Build.
+
+### Settings and caller overrides
+
+Follow [Smart defaults, local overrides](../../Ways-of-Working/Principles/Software-Design.md#smart-defaults-local-overrides):
+shared defaults are overridden by repository settings in the optional
+`.github/release.config.yml`, then by explicitly supplied supported caller
+inputs for that invocation. Omitted caller inputs preserve repository settings;
+they do not overwrite them with an input's default. The implementing workflow
+or action documents its exact supported caller surface and validates it through
+the same settings resolver rather than maintaining another algorithm.
+
+`DefaultBump` accepts exactly `patch`, `minor`, or `major`. Its documented shared
+default is `patch`; omitting the configuration file or field inherits that value.
+A caller can deliberately select another supported level. Unknown setting names,
+null or empty values, and values outside the documented set fail validation,
+even when a narrower override or bump label exists.
+
+| Setting | Shared default | Repository override | Supported caller override |
+| --- | --- | --- | --- |
+| `DefaultBump` | `patch` | `DefaultBump` in `.github/release.config.yml` | Explicitly supplied caller override supported and documented by the invoked producer for this setting. |
+
+For example, a repository can select minor as its normal level without requiring
+a minor label on every publishing PR:
```yaml
# .github/release.config.yml
-DefaultBump: patch
+DefaultBump: minor
```
| Label | Meaning | Valid combination |
| --- | --- | --- |
-| `release:patch` | Resolve the next patch version, overriding the configured default. | Alone or with `release:pre-release`. |
-| `release:minor` | Resolve the next minor version, overriding the configured default. | Alone or with `release:pre-release`. |
-| `release:major` | Resolve the next major version, overriding the configured default. | Alone or with `release:pre-release`. |
-| `release:pre-release` | Publish the open pull request as a prerelease using the resolved bump. | With one explicit bump or a configured default; never with `release:skip`. |
+| `release:patch` | Resolve the next patch version, overriding the effective default. | Alone or with `release:prerelease`. |
+| `release:minor` | Resolve the next minor version, overriding the effective default. | Alone or with `release:prerelease`. |
+| `release:major` | Resolve the next major version, overriding the effective default. | Alone or with `release:prerelease`. |
+| `release:prerelease` | Publish the open pull request as a prerelease using the resolved bump. | With one explicit bump or the effective default; never with `release:skip`. |
| `release:skip` | Run validation without resolving or publishing a version. | Alone. |
Resolve the decision in this order:
-1. Validate `DefaultBump` when present and reject conflicting owned labels.
- An invalid setting is an error even when an explicit label is supplied.
- Bare and unrelated labels do not participate.
+1. Validate supplied settings and the effective configuration, then reject
+ conflicting owned labels. An invalid setting is an error even when another
+ input would supply a valid level. Bare and unrelated labels do not participate.
2. Honor a valid `release:skip` as the explicit no-release decision and stop bump
resolution.
-3. Use the single owned bump label when present; otherwise use the configured
- `DefaultBump`. Record the chosen level and whether the label or setting
- supplied it.
-4. If neither supplies a level, fail with a missing-decision error that tells the
- author to select a bump, configure the default, or choose `release:skip`.
- There is no built-in patch fallback. Prerelease mode does not supply a bump.
-
-| PR input | `DefaultBump` | Decision-check result |
+3. Use the single owned bump label when present; otherwise use the valid
+ effective `DefaultBump`. Record whether the label, caller input, repository
+ setting, or shared default supplied the level.
+4. If neither resolves a valid level, fail with an actionable decision error.
+ Inheriting the documented patch default is a valid policy decision; choosing
+ patch to recover from invalid or unresolved input is forbidden. Prerelease
+ mode does not supply a bump.
+
+| PR input | Effective default and source | Decision-check result |
| --- | --- | --- |
-| `release:major` | `patch` or absent | Pass: explicit major overrides the default. |
-| No owned release labels | `minor` | Pass: configured minor; record the setting as the source. |
-| No release decision | Absent | Fail: missing decision; merge blocked. |
-| `release:skip` alone | Valid or absent | Pass: no release; no bump is required. |
-| `release:pre-release` alone | `patch` | Pass: configured patch in prerelease mode. |
-| `release:pre-release` alone | Absent | Fail: mode does not supply a bump; merge blocked. |
+| `release:major` | Valid `patch` from any supported scope | Pass: explicit major overrides the default. |
+| No owned release labels | No repository or caller override; shared `patch` | Pass: documented patch default; no per-PR bump label required. |
+| No owned release labels | Repository `minor`; caller omitted | Pass: repository minor; record the setting as the source. |
+| No owned release labels | Repository `major`; explicit caller `patch` | Pass: caller patch overrides repository major. |
+| `release:skip` alone | Valid default | Pass: no release; no bump is required. |
+| `release:prerelease` alone | Valid effective `minor` | Pass: default minor in prerelease mode. |
+| No bump label | No valid effective default can be resolved | Fail: unresolved decision; no invented fallback. |
| Multiple bump labels, or skip with another owned release label | Any | Fail: conflicting decisions; no fallback. |
-| Any | Invalid value | Fail: invalid configuration; no fallback. |
+| Any, including an explicit bump or skip | Invalid supplied setting | Fail: invalid configuration; no fallback or masking by an override. |
-- **First release** starts from a baseline (`v0.1.0` or `v1.0.0`). Pre-`1.0.0`
- breaking changes are `release:minor` per [SemVer §4](https://semver.org/#spec-item-4);
- `release:major` is never auto-detected pre-`1.0.0`.
+- **First release** uses `0.0.0` as the version base when no stable history
+ exists. The resolved patch, minor, or deliberate major bump produces
+ `0.0.1`, `0.1.0`, or `1.0.0`, respectively. Pre-`1.0.0` breaking changes
+ use minor per [SemVer §4](https://semver.org/#spec-item-4); reaching `1.0.0`
+ is a deliberate major decision, never an auto-detected breaking classification.
- The tag is created on the commit now at the head of the release branch —
squash, merge-commit, and rebase strategies alike.
+### Pull request decision record
+
+After inspecting the complete change, an author on an invoked route records the
+human-readable decision in the conditional `Release decisions` block from [PR
+Format](../../Ways-of-Working/PR-Format.md#record-release-decisions-only-when-invoked).
+The block and the effective resolver inputs must agree:
+
+- `Release: Yes` states why the change affects the artifact or a supported
+ consumer contract, then records `Version bump`, `Mode`, and `Labels`.
+- `Release: No` states the no-release evidence and reports only
+ `release:skip`.
+- `Labels` names the exact applied `release:*` labels. Use `None` when a valid
+ configured default supplies a release level without an override label.
+
+The resolver still reads labels and configuration as its machine inputs; the
+block makes the reviewed decision and its evidence visible. A route without an
+invocation has neither the block nor any `release:*` labels.
+
### Required pre-merge decision check
-PR CI runs the resolver read-only against the candidate release settings and
-current owned labels, without creating tags, releases, or published artifacts.
+PR CI runs the resolver read-only against the candidate release settings,
+supported caller inputs, and current owned labels, without creating tags,
+releases, or published artifacts.
An existing version-resolution check may own this validation; do not duplicate
the resolver. The check reports the effective decision and its source, not a
promised final stable version.
-The validator runs for every PR targeting a release branch, including changes
-that will not publish. It re-runs when source, release labels, or release settings
-change, so a stale result is not evidence for different inputs. Missing,
-invalid, or conflicting decisions produce a failed check with an actionable
-error. A valid skip reports success with a no-release result; path filters do
-not skip the validator.
+The validator runs for every PR targeting a managed release route, including
+native producer routes, changes that will not publish, and repositories without
+a release configuration file. It re-runs when source, release labels, release
+settings, supported caller inputs, or the effective pipeline changes, so a stale
+result is not evidence for different inputs. Missing, invalid, or conflicting decisions produce a failed
+check with an actionable error. A valid skip reports success with a no-release
+result; path filters do not skip the validator.
Configure the check's exact name as required in the protected branch's ruleset
or branch protection, following [Merge Automation](../merge-automation/spec.md).
@@ -170,7 +244,7 @@ either: rerun the existing release with the same artifact and version under the
- **Branch-level** — a prerelease-type branch publishes on every push, using the
branch name as the identifier: `v1.3.0-dev.1`, `v1.3.0-dev.2`, …
-- **PR-level** — `release:pre-release` with a resolved explicit or configured bump publishes
+- **PR-level** — `release:prerelease` with a resolved explicit or default bump publishes
`v-.`: `base` is the next version from that bump,
`identifier` is the normalized branch name, and `counter`
auto-increments per push.
@@ -182,13 +256,13 @@ either: rerun the existing release with the same artifact and version under the
## Path filtering
-`.github/release.config.yml` declares `release-paths` as ordered include/exclude
-globs (excludes win). The workflow **always runs** so validation executes on
-every merge; only the release step is skipped when no artifact-affecting path
-changed.
+When present, `.github/release.config.yml` declares `release-paths` as ordered
+include/exclude globs (excludes win). On an invoked route, the workflow
+**always runs** so validation executes on every merge; only the release step is
+skipped when no artifact-affecting path changed.
Derive these paths from the delivered product and its
-[audience-facing contracts](../../Ways-of-Working/PR-Format.md#detecting-the-change-type),
+[audience-facing contracts](../../Ways-of-Working/PR-Format.md#identify-the-readers),
not directory names alone. Include callable workflows and build configuration
that changes delivered runtime requirements or behavior. Do not retain an
exclusion that overrides an included consumer interface or artifact input.
@@ -207,20 +281,50 @@ release-paths:
The GitHub Release **name** is the resolved version. Its **body** preserves the
release-bound PR title and complete description, using
-[PR Format](../../Ways-of-Working/PR-Format.md#description-structure) as the
-authoring contract. Summary, user-facing changes, adoption, release impact,
-consumer change records, template evidence, and both ending details blocks stay
-intact. There is no parallel JSON/YAML contract and no extraction of only the
-user-facing headings.
+[PR Format](../../Ways-of-Working/PR-Format.md#write-the-description) as the
+authoring contract. The concise summary, shareable-summary marker, non-empty
+classified change sections, reader-facing prose, section-scoped `Technical
+details` and `Related references`, and conditional `Release decisions` block
+stay intact. There is no parallel JSON/YAML contract and no extraction of only
+selected headings or evidence blocks.
+
+The notes are the sufficient consumer upgrade record. Each release explains its
+complete delta from the identified consumer-change baseline: what changed, why,
+affected supported uses, compatibility, and exact actions with applicable
+prerequisites, ordering, and verification, or an explicit no-action result and
+its compatibility basis. Necessary old-to-new examples stay in the note.
+Consumer instructions appear in each result's prose and examples; scoped
+technical details retain their supporting evidence.
+
+For internal-only work without a classified section, the summary contains the
+adoption or explicit no-action result and the supporting block after its marker
+contains the applicable evidence. Preserve that permitted PR Format shape rather
+than manufacturing a classified result solely to hold metadata.
+
+Consumers read every applicable record after their actual consumed baseline
+through their chosen target in release order, then compose the necessary
+actions. Later notes explain superseded actions while preserving required
+intermediate operations. Reading the records does not require installing every
+intermediate version; an intermediate installation or run is required only when
+explicitly stated. PR and diff links provide optional depth. Missing required
+instructions are an evidence gap to resolve in the notes, not a routine source
+investigation for consumers.
+
+[Resource docs](../../Ways-of-Working/Documentation-Model.md#current-product-guidance-and-release-history)
+show supported target-state behavior and usage. They do not hold release-specific
+migration history or replace the instructions in the release record.
### Bind the note to the released source
1. **Resolve the evidence with the version.** Identify the release-bound PR or
ad hoc context and the immutable source to build. Resolve the version base
- and the source comparison baseline; confirm that the consumer record
- describes that delta. Capture the applicable title and complete body together
- with the PR URL or context reference, source identity, and snapshot time.
- Retain that snapshot as release evidence.
+ and the source comparison baseline; reconcile every delivered consumer delta
+ in that range, including earlier merged or skipped changes. Confirm that each
+ applicable section contains sufficient adoption instructions or a supported
+ no-action result and that its technical details support the claim. Capture
+ the applicable title and complete body together with the PR URL or context
+ reference, source identity, and snapshot time. Retain that snapshot as release
+ evidence.
2. **Keep identity separate from authored prose.** Resolve the actual publication
coordinates through the existing version pipeline, not a number assigned by
the PR author. Carry them and the snapshot through Build and Test with the
@@ -246,24 +350,25 @@ release note:
Version base and change baseline can differ, particularly for prereleases and
bundled promotion. Recording both avoids presenting a versioning calculation as
-proof of the code a consumer crosses. The target template identity and
-compatibility evidence come from the authored record; a publisher does not
-substitute the latest template or infer historical compatibility from current
-documentation.
+proof of the code a consumer crosses. When a result affects an integration
+template, its identity and compatibility evidence come from that result's
+technical details; a publisher does not substitute the latest template or infer
+historical compatibility from current documentation.
### Release-bound records
| Publication path | Authored record |
| --- | --- |
| Single merged PR | That PR's complete title and description, reconciled with the resolved source comparison. |
-| Bundled release | The release-bound integration PR covers every bundled delta from the declared change baseline, not just the most recent feature PR. It links the contributing work as supporting evidence. |
-| Optional ad hoc dispatch | Complete reviewed release-note context with the same adoption, consumer-change, template, and release-impact evidence. Record the dispatch source and reason; do not create or imply an empty PR. |
+| Bundled release | The release-bound integration PR covers every bundled consumer delta and required action from the declared change baseline, including earlier merged or skipped changes, not just the most recent feature PR. Grouping results retains those instructions; contributing PRs are optional supporting depth. |
+| Optional ad hoc dispatch | Complete reviewed release-note context with the same classified structure and applicable result-specific evidence. Record the dispatch source and reason; do not create or imply an empty PR. |
| Prerelease | The PR or integration record appropriate to that published source, captured for that release. Later edits to the final PR do not overwrite the prerelease snapshot or attribute unreleased behavior to it. |
-If the relationship between a record and its source cannot be established,
-stop the affected publication and register the evidence gap. The process does
-not substitute the newest note, guess a baseline, or treat an empty adoption
-section as a no-action result.
+If the relationship between a record and its source cannot be established, or
+required consumer instructions are missing, stop the affected publication and
+register the evidence gap. The process does not substitute the newest note,
+guess a baseline, or treat missing instructions or applicable supporting
+evidence as a no-action result.
### Correct published metadata without changing history
@@ -379,9 +484,10 @@ release, and its runs are serialised like any other.
| Surface | Where |
| --- | --- |
-| Release branches + type | `.github/release.config.yml` |
-| Optional default bump | `DefaultBump` in `.github/release.config.yml` |
-| Explicit bump / prerelease / skip | `release:` PR label |
+| Release Management applicability | effective target-route pipeline, including shared workflows and native producers |
+| Release branches + type | optional `.github/release.config.yml`; the default branch is stable when omitted |
+| Default bump and overrides | documented shared `DefaultBump: patch`, repository settings, then supported caller inputs |
+| Explicit bump / prerelease / skip | `release:` PR label on an invoked route |
| Pre-merge decision validation | named PR check required by the branch ruleset or protection |
| Optional ad hoc release | `workflow_dispatch` inputs |
| Path filter | `.github/release.config.yml` |
diff --git a/src/docs/Capabilities/release-management/index.md b/src/docs/Capabilities/release-management/index.md
index cf760a7..0a99ebb 100644
--- a/src/docs/Capabilities/release-management/index.md
+++ b/src/docs/Capabilities/release-management/index.md
@@ -16,8 +16,8 @@ no tagging ritual.
| Page | Description |
| --- | --- |
-| [Spec](spec.md) | Requirements for release management — automatic, policy-driven, versioned releases driven entirely on the GitHub platform. |
-| [Design](design.md) | How release management is built — a shared reusable workflow that resolves an explicit or configured SemVer bump, builds once, and publishes. |
+| [Spec](spec.md) | Requirements for release management — validated defaults, reviewed overrides, immutable artifacts, and complete consumer release records. |
+| [Design](design.md) | How release management is built — effective defaults, owned overrides, source-bound notes, and build-once publication. |
| [Publishing Targets](design-publishing-targets.md) | The contract every publishing destination documents, with GitHub Releases as the reference target. |
diff --git a/src/docs/Capabilities/release-management/spec.md b/src/docs/Capabilities/release-management/spec.md
index 67579fd..25900be 100644
--- a/src/docs/Capabilities/release-management/spec.md
+++ b/src/docs/Capabilities/release-management/spec.md
@@ -1,6 +1,6 @@
---
title: Spec
-description: Requirements for release management — automatic, policy-driven, versioned releases driven entirely on the GitHub platform.
+description: Requirements for release management — validated defaults, reviewed overrides, immutable artifacts, and complete consumer release records.
---
# Release Management — Spec
@@ -13,35 +13,48 @@ releasing. Releasing MUST be automatic, predictable, and driven entirely on the
GitHub platform — a contributor focuses on the code they contribute, not a
release CLI, a hand-edited version file, or a tagging convention.
+A target route participates when its effective pipeline produces a versioned,
+immutable output consumed by version. This includes a shared Release Management
+workflow and a native producer pipeline; the contract is not conditional on one
+implementation's name. The optional `.github/release.config.yml` file refines a
+managed route's settings but does not create a release pipeline, and its absence
+does not opt a managed route out.
+
### Principles
This capability rests on the [Principles](../../Ways-of-Working/Principles/index.md):
- **[Everything as Code](../../Ways-of-Working/Principles/Engineering-Practices.md#everything-as-code).** The release process and version decision are version-controlled, never a GUI action or manual tag.
-- **[Decision before change](../../Ways-of-Working/Principles/AI-First-Development.md#decision-before-change).** The pull request is the decision point; its review gate approves the code *and* the release. An owned bump label records a per-change decision; a version-controlled repository default records the policy used when no level is supplied.
+- **[Decision before change](../../Ways-of-Working/Principles/AI-First-Development.md#decision-before-change).** The pull request is the decision point; its review gate approves the code *and* the release. An owned bump label records a per-change override; a documented effective default records the policy used when no level is supplied.
+- **[Smart defaults, local overrides](../../Ways-of-Working/Principles/Software-Design.md#smart-defaults-local-overrides).** Shared defaults make an unconfigured managed route useful; repository settings and supported caller inputs provide deliberate narrower overrides.
- **[Extensible by default](../../Ways-of-Working/Principles/Software-Design.md#extensible-by-default).** The rules are technology-agnostic at the core, with defined extension points per artifact type. A new artifact type supplies a convention and a publish step, not a new process.
## Scope
-Applies to any repository that produces a versioned artifact on merge to a
-release branch. One test decides applicability: **does merging produce a
-versioned, immutable output that something else consumes by version?** If yes,
-this capability governs the release. If no, there is nothing to release.
+Applies to a target route that produces a versioned artifact, whether through a
+shared workflow or a native producer pipeline. One product test decides
+applicability: **does merging produce a versioned, immutable output that
+something else consumes by version?** If yes, this contract governs the route.
+If no, there is nothing to release and the pull request carries neither the
+`Release decisions` block nor `release:*` labels.
## Requirements
- **Semantic versioning.** Versions follow [SemVer 2.0.0](https://semver.org/) (`vMAJOR.MINOR.PATCH`), derived automatically — never written by hand.
-- **A resolved PR release decision.** The repository MAY configure `DefaultBump` as `patch`, `minor`, or `major`; invalid values MUST fail. Multiple owned bump labels, or `release:skip` combined with another owned release label, MUST fail. A valid `release:skip` MUST select no release without resolving a bump. For publishing decisions, one owned `release:patch`, `release:minor`, or `release:major` label MUST take precedence over the configured default; without a bump label, a valid `DefaultBump` MUST supply the level; without either source, automation MUST fail with a missing-decision error, never assume `patch`. `release:pre-release` MAY use either the explicit or configured bump; the mode alone does not supply a level. Bare or unrelated labels MUST be ignored. Conventional commit messages are **not** required.
-- **A release per merge.** One eligible merged PR with a resolved bump to a release branch is one release, and the PR review gate is the release gate. `release:skip` validates without publishing. This pull-request path is the required release interface.
-- **Decision validation blocks merge.** Every PR targeting a release branch MUST receive a named release-decision CI check required by the branch ruleset or protection. Missing decisions, invalid defaults, and conflicting owned labels MUST fail that check before merge, not only during publication. Source, release-label, and release-settings changes MUST re-evaluate the decision. A failing, pending, or absent required result MUST block both manual and automated merge; a log message, warning, or skipped validator is not enforcement. A valid `release:skip` MUST report a successful no-release decision, not skip the check.
+- **Release behavior determines applicability.** Release Management MUST evaluate every pull request targeting a managed release route, including native producer routes and routes without `.github/release.config.yml`. A route without versioned release behavior MUST NOT require, apply, or report the `Release decisions` block or any `release:*` label.
+- **Producer compatibility is verified, not inferred.** Authors MUST verify the effective producer revision's settings and owned-label mapping. A differing released interface MUST have a verified adapter or producer/configuration migration before the canonical signals are used. Unsupported signals MUST block finalization and required decision validation, not become ignored skip requests or an excuse to classify a managed route as unmanaged. The producer's PR/release record owns its exact adoption actions.
+- **Settings have documented defaults and supported overrides.** Release automation MUST document its setting names, accepted values, shared defaults, and supported caller overrides. Repository settings MUST override shared defaults; explicitly supplied supported caller inputs MUST override repository settings for that invocation. Unknown settings and invalid supplied values MUST fail even when a narrower override or explicit bump label exists. Omission MUST inherit a documented default rather than require configuration to become usable.
+- **A resolved PR release decision.** `DefaultBump` accepts exactly `patch`, `minor`, or `major` and has the shared default `patch`. Multiple owned bump labels, or `release:skip` combined with another owned release label, MUST fail. A valid `release:skip` MUST select no release without resolving a bump. For publishing decisions, one owned `release:patch`, `release:minor`, or `release:major` label MUST take precedence over the valid effective default; without a bump label, that default MUST supply the level without requiring a per-PR bump label. If neither source resolves a valid level, automation MUST fail with an actionable decision error; it MUST NOT recover from invalid input by selecting patch. `release:prerelease` MAY use either the explicit or default bump; the mode alone does not supply a level. Bare or unrelated labels MUST be ignored. Conventional commit messages are **not** required.
+- **A release per merge.** One eligible merged PR with a resolved bump to an invoked release route is one release, and the PR review gate is the release gate. `release:skip` validates without publishing. This pull-request path is the required release interface.
+- **Decision validation blocks merge.** Every PR targeting an invoked release route MUST receive a named release-decision CI check required by the branch ruleset or protection. Missing decisions, invalid defaults, and conflicting owned labels MUST fail that check before merge, not only during publication. Source, release-label, and release-settings changes MUST re-evaluate the decision. A failing, pending, or absent required result MUST block both manual and automated merge; a log message, warning, or skipped validator is not enforcement. A valid `release:skip` MUST report a successful no-release decision, not skip the check.
- **Ad hoc release is optional.** An implementation MAY expose `workflow_dispatch` when its product needs an ad hoc release outside the merge flow; implementations are not required to support it. A dispatch MUST require an explicit release decision and release-note context, and MUST use the same version, build, validation, immutability, and publication controls as a merged pull request. A direct push MUST NOT be an ad hoc release interface, and an empty pull request MUST NOT be created solely to trigger a release.
- **Version before build.** The version MUST be resolved before the artifact is built, so the version is part of the artifact's identity rather than a label attached afterwards.
- **Build once.** The artifact MUST be built exactly once and MUST NOT be altered after it is built. The same bytes flow through validation and publishing. Rebuilding to publish means the tested artifact and the published artifact are different artifacts.
-- **Stable and prerelease.** Every release is either **stable** (the latest version to adopt) or a **prerelease** (testable, not promoted to latest). A prerelease MUST be obtainable from an open pull request carrying `release:pre-release`, using its explicit or configured bump, and/or from a prerelease branch.
+- **Stable and prerelease.** Every release is either **stable** (the latest version to adopt) or a **prerelease** (testable, not promoted to latest). A prerelease MUST be obtainable from an open pull request carrying `release:prerelease`, using its explicit or default bump, and/or from a prerelease branch. A configured release candidate is a prerelease with its own candidate series, not an additional owned release label.
- **Serialised releases.** Only one release process runs against a given version of the codebase (the same ref) at a time. A release mutates shared, version-anchored state — the tag, the version counter, the published artifact — so overlapping runs on the same ref MUST NOT race, and an in-flight release is never interrupted.
- **A single production authority.** Exactly one branch is in charge of the production (stable) version, so consumers get one unambiguous latest stable release and two branches can never publish competing production releases.
-- **Notes from the contributor's own words.** The GitHub Release name is the version; its body MUST preserve the release-bound pull request title and complete description, or equivalent complete release-note context for an optional ad hoc dispatch. The authored record follows [PR Format](../../Ways-of-Working/PR-Format.md#description-structure); adoption and technical details MUST NOT be omitted or summarized away.
-- **Only artifact-affecting changes release.** A change that does not affect the delivered artifact or its supported consumer contracts MUST carry `release:skip` and MUST NOT produce a release — though validation still runs on every merge. Documentation and internal CI configuration qualify only when they meet that condition. An Action or reusable workflow is itself a product for its callers; its interface and behavior MUST NOT be dismissed as internal tooling because of the file path.
+- **Notes from the contributor's own words.** The GitHub Release name is the version; its body MUST preserve the release-bound pull request title and complete description, or equivalent complete release-note context for an optional ad hoc dispatch. The authored record follows [PR Format](../../Ways-of-Working/PR-Format.md#write-the-description); classified results and their section-scoped technical details and related references MUST NOT be omitted or summarized away.
+- **Only artifact-affecting changes release.** On an invoked release route, a change that does not affect the delivered artifact or its supported consumer contracts MUST carry `release:skip` and MUST NOT produce a release — though validation still runs on every merge. Documentation and internal CI configuration qualify only when they meet that condition. An Action or reusable workflow is itself a product for its callers; its interface and behavior MUST NOT be dismissed as internal tooling because of the file path.
- **Immutable references.** Consumers pin to the most immutable reference available — a container digest or a commit SHA — never a mutable tag.
- **Publish through a target contract.** Every publishing destination is reached through the same [publishing-target contract](design-publishing-targets.md), so the release process stays one process regardless of how many destinations a repository has. Adding a destination supplies a contract and a publish step; it MUST NOT change the release process.
- **All-or-nothing across targets.** Where a repository publishes one artifact to more than one destination, a version MUST NOT end up present on some destinations and absent from others. Partial publication is a failure, reported as one, and resumed by completing the remaining destinations with the same immutable artifact and version.
@@ -50,10 +63,12 @@ this capability governs the release. If no, there is nothing to release.
### Release evidence
-- **Incremental consumer contract.** Every release MUST describe its consumer-facing delta against an identified release/source baseline, including applicability, exact actions, and verification, or explicit no-action evidence. Breaking behavior MUST be documented independently of its semantic-version classification. An applicable integration template MUST be identified by repository and verified compatible immutable commit, with producer-source compatibility evidence and linked template work or a justified no-change result.
+- **Evidence stays with the result it supports.** Consumer instructions MUST appear in the applicable change classifier's reader-facing prose and examples. Supporting validation, source, and template evidence MUST appear in that section's `Technical details` block. For internal-only work with no classified section, the summary MUST carry the adoption or no-action result and the supporting block after its marker MUST carry the applicable evidence under [PR Format](../../Ways-of-Working/PR-Format.md#close-each-section-with-supporting-details). Otherwise, a global consumer, template, or maintainer evidence block MUST NOT substitute for result-specific evidence.
+- **Incremental consumer contract.** Every release MUST explain its complete consumer-facing change against an identified release/source baseline: what changed, why, affected supported uses, compatibility, and exact applicable adoption actions with prerequisites, ordering, and verification, or an explicit no-action result with its compatibility basis. Breaking behavior MUST be explicit independently of its semantic-version classification. When an integration template is affected, identify its repository and verified compatible immutable commit, with producer-source compatibility evidence and linked template work or a justified no-change result.
+- **Sufficient upgrade history.** Reading every applicable release record after a consumer's actual consumed baseline through its chosen target in release order MUST be sufficient to compose the required alignment actions. Notes MUST identify any required intermediate installation or run and explain when later instructions supersede earlier actions; reading a release MUST NOT itself require installing that version. PRs, diffs, and historical product docs MAY provide optional depth, but MUST NOT be necessary to discover required instructions. Missing instructions MUST be treated as evidence gaps, not implicit no-action results. Resource docs remain focused on supported target-state behavior and usage under the [Documentation Model](../../Ways-of-Working/Documentation-Model.md#current-product-guidance-and-release-history).
- **Resolved coordinates.** The release process MUST record the actual target version, tag, immutable source and artifact identity, effective release decision and its source, version-computation base, and consumer-change baseline. The version base and change baseline MUST be distinguished when they differ. A first release MUST identify its initial versioning baseline and lack of a prior release. Authors MUST NOT assign a final version before resolution.
- **Traceable publication.** Generated identity and provenance MAY surround the authored note as a distinct envelope; they MUST NOT replace or rewrite it. The release MUST retain the note's source identity and snapshot provenance so its relationship to the published code is inspectable. Every destination carrying release notes, including downstream propagation, MUST receive the complete record.
-- **Correct release scope.** A bundled release's integration PR MUST cover every bundled consumer delta. An optional ad hoc release MUST provide equivalent evidence without implying a nonexistent PR. A prerelease MUST preserve the note appropriate to its immutable published source, not a later final-PR description that describes different code.
+- **Correct release scope.** The release-bound record MUST cover the complete delivered change since its identified consumer-change baseline, including earlier merged or skipped changes in that range. A bundled release's integration PR MUST preserve every bundled consumer delta and required action when grouping results. An optional ad hoc release MUST provide equivalent evidence without implying a nonexistent PR. A prerelease MUST preserve the note appropriate to its immutable published source, not a later final-PR description that describes different code.
- **Metadata-only correction.** A correction to published notes MUST retain an audit of the original and corrected content, reason, supporting source evidence, actor, and time. It MUST NOT alter release artifacts, tags, source identities, or the behavior attributed to a version. Unverifiable historical facts MUST be registered as gaps, not guessed.
### Consumer update policies
@@ -73,18 +88,21 @@ Because versions are semantic, immutable, and published once, a consumer can ado
## Success criteria
- Merging an eligible PR with an explicit or configured bump produces a GitHub Release, a git tag, and (where one exists) a published artifact, with no manual step.
-- For a publishing PR, an explicit owned bump label overrides the configured default; without that label, a valid `DefaultBump` supplies the level and is recorded as its source.
-- A PR with no explicit level, configured default, or valid no-release decision fails the required decision check and cannot merge. Invalid defaults and conflicting owned labels also block merge rather than selecting a fallback.
-- Removing the only decision source or changing its inputs re-evaluates the PR check; a prior result does not validate different inputs.
-- An open pull request carrying `release:pre-release` and an explicit or configured bump publishes a prerelease without promoting it to latest.
+- A pull request targeting a managed release route, including a native producer route, is evaluated even when `.github/release.config.yml` is absent; an unmanaged route carries no release decision block, label, or check.
+- With no repository setting, caller override, or bump label, a publishing PR resolves the documented patch default. A repository default and supported caller override resolve in that order, and an explicit owned bump label overrides the valid effective default.
+- The resolver records the effective value and its source. Invalid supplied settings and conflicting owned labels block merge even when another input would supply a valid level; no success-shaped fallback occurs.
+- Removing a bump override re-evaluates the PR check against the effective default; changing source, settings, or route inputs also re-evaluates it. A prior result does not validate different inputs.
+- An open pull request carrying `release:prerelease` and an explicit or default bump publishes a prerelease without promoting it to latest.
- The artifact that consumers download is byte-identical to the artifact that passed validation.
-- A documentation-only merge carrying `release:skip` produces no new version but still runs its CI checks.
+- On an invoked release route, a documentation-only merge carrying `release:skip` produces no new version but still runs its CI checks.
- Two release runs for the same ref never overlap; the second waits for the first to finish rather than racing it.
- Only the single production branch ever publishes a stable release.
- A version that reaches one publishing target reaches all of them, or the release is reported as failed.
- Every release is linkable and records its immutable artifact reference.
-- The published authored title and body match the release-bound snapshot in full, including adoption, consumer/template evidence, and maintainer details.
-- A consumer can identify the actual target, version base, change baseline, and any applicable compatible template without relying on a moving branch, alias, or today's documentation.
+- The published authored title and body match the release-bound snapshot in full, including every classified result and its section-scoped technical details and related references.
+- A consumer can compose the applicable actions from its actual baseline through a chosen target using only the ordered release records, including explicit no-action releases. Intermediate installations or runs are required only when stated in those records.
+- Required old-to-new instructions remain in the notes; resource docs describe supported target-state usage, and an omitted instruction is reported as an evidence gap rather than delegated to PR or source inspection.
+- Where a result affects consumers or an integration template, a consumer can identify the actual target, version base, change baseline, and compatible template without relying on a moving branch, alias, or today's documentation.
- A bundled or ad hoc note covers its complete change range, and a prerelease note never gains instructions for code absent from that prerelease.
- A published-note correction is traceable to released-source evidence while all artifact and source identities remain unchanged.
@@ -94,5 +112,5 @@ Because versions are semantic, immutable, and published once, a consumer can ado
- [Publishing Targets](design-publishing-targets.md) — the contract each destination documents.
- [Documentation Model](../../Ways-of-Working/Documentation-Model.md) — why this spec holds only the why and the what.
- [Automation Labels](../../Ways-of-Working/Automation-Labels.md) — why release labels are owned by the `release:` namespace.
-- [PR Format](../../Ways-of-Working/PR-Format.md) — the change-type labels that drive the bump.
+- [PR Format](../../Ways-of-Working/PR-Format.md) — the authored release record and conditional release-decision block.
- [Dependency Updates](../dependency-updates/spec.md) — update PRs are artifact-affecting and release through this capability.
diff --git a/src/docs/Capabilities/vscode-extension-framework/design.md b/src/docs/Capabilities/vscode-extension-framework/design.md
index 53ccff9..ab8e226 100644
--- a/src/docs/Capabilities/vscode-extension-framework/design.md
+++ b/src/docs/Capabilities/vscode-extension-framework/design.md
@@ -29,12 +29,15 @@ flowchart LR
```
- **Find version** — validate the release decision and compute the version once,
- from the latest `vX.Y.Z` tag or release plus the explicit or configured bump.
+ through the shared release resolver's authoritative version base and valid
+ effective bump, not a separate latest-tag algorithm. Resolve
+ the canonical release identity and any declared native numeric mapping before
+ Build; retain both with their source evidence.
Independent of the other stages and required by the merge ruleset; a missing
decision is a failed check, not a post-merge surprise.
- **Lint & type-check** — static analysis and the type checker. Independent, so
it fails fast in parallel with the build.
-- **Build** — stamp the computed version into the manifest, compile the
+- **Build** — stamp the resolved native extension version into the manifest, compile the
production bundle, and package **one** VSIX. Uploads the bundle, the VSIX, and
the stamped manifest as artifacts.
- **Test** — download a real editor host and run the extension test suite
@@ -47,13 +50,17 @@ flowchart LR
The version is computed once and flows through the pipeline as artifacts, so the
thing that ships is the thing that was tested:
-1. **Find version** decides `vX.Y.Z` from tags plus the resolved explicit or configured bump.
-2. **Build** stamps it into `package.json` (and `package-lock.json`), compiles
+1. **Find version** decides the canonical release version and validated native
+ extension version together, before Build.
+2. **Build** stamps the resolved native version into `package.json` (and
+ `package-lock.json`), compiles
the bundle, and runs the packaging CLI to produce a single VSIX. The stamped
manifest is uploaded alongside the VSIX so the manifest under test — including
the version the running extension reports — matches the packaged artifact.
3. **Test** restores that bundle and manifest and tests them.
-4. **Release** restores and publishes that same VSIX.
+4. **Release** restores and publishes that same VSIX. Its GitHub Release uses
+ the canonical identity and records the native mapping; enabled marketplaces
+ receive the unchanged VSIX and the corresponding native version/channel.
Build, test, and release never re-compile or re-package; they pass the built
artifact forward.
@@ -103,20 +110,40 @@ Versioning is [Release Management](../release-management/design.md) applied to a
VSIX artifact — this framework does not re-implement it:
- The shared resolver uses one explicit owned bump label or, without one, the
- optional `DefaultBump` in `.github/release.config.yml`. A valid `release:skip`
- reports a no-release decision without skipping validation; otherwise a missing
- level fails the required PR decision check. Invalid defaults and conflicting
- owned labels also fail. No implicit patch is selected.
-- The version check re-evaluates source, release-label, and release-settings
- changes and follows the shared
+ valid effective `DefaultBump`. The documented shared patch default,
+ repository settings, and supported caller inputs resolve under the shared
+ [settings contract](../release-management/design.md#settings-and-caller-overrides).
+ A valid `release:skip` reports a no-release decision without skipping
+ validation. Invalid supplied settings and conflicting owned labels fail;
+ another input never masks them.
+- The version check re-evaluates source, release labels, release settings,
+ supported caller inputs, and the effective pipeline, following the shared
[pre-merge gate](../release-management/design.md#required-pre-merge-decision-check).
-- The version is computed once and stamped into the manifest; it is never
- hand-edited.
-- A prerelease is requested by `release:pre-release` with a resolved bump on
+- Canonical and native versions are resolved once before Build; the native
+ extension version is stamped into the manifest, never hand-edited.
+- A prerelease is requested by `release:prerelease` with a resolved bump on
an open pull request (or by a prerelease branch), producing a prerelease VSIX
that is never promoted to latest. When such a build is also published to the
- VS Code Marketplace, it goes out with `@vscode/vsce publish --pre-release` and
- an odd minor-version number, the Marketplace's pre-release-channel convention.
+ VS Code Marketplace, its native prerelease flag and declared native version
+ mapping must agree with the canonical identity.
+
+### Marketplace version mapping
+
+The adapter declares stable and prerelease numeric-version mappings together
+before Marketplace publication is enabled. The Marketplace accepts a three-part
+numeric version and a separate prerelease flag, not an arbitrary canonical
+SemVer suffix. No direct stable mapping plus an independently invented
+prerelease mapping is assumed.
+
+The producer's mapping contract must identify supported canonical identities,
+reserve distinct native coordinates, define series/counter allocation, and
+prove collision-free stable/prerelease publication and retry behavior. An
+odd-minor convention applies only when the stable mapping reserves that space;
+it is not a universal conversion for arbitrary stable minor versions. Record
+both identities with immutable producer and artifact evidence. Unsupported
+mappings and collisions fail before build/publication rather than silently
+changing a version or channel. The GitHub VSIX path does not require Marketplace
+publication, but an enabled required target is not silently skipped.
## Publishing and distribution
@@ -175,7 +202,7 @@ Every external Action is pinned to a commit SHA; organization- or initiative-own
| Adoption (opt-in) | a short caller workflow that calls the reusable workflow |
| Host + OS matrix, marketplace toggle, extras | `.github/vscode-extension.yml` |
| Explicit bump / prerelease / skip | owned pull-request label |
-| Optional default bump | `DefaultBump` in `.github/release.config.yml` |
+| Default bump and overrides | shared `DefaultBump: patch`, repository settings, and supported caller inputs |
| Pre-merge decision validation | version check required by the branch ruleset or protection |
| Release branches + path filter | `.github/release.config.yml` ([Release Management](../release-management/design.md)) |
| Marketplace publish tokens | a GitHub environment's secrets |
diff --git a/src/docs/Capabilities/vscode-extension-framework/spec.md b/src/docs/Capabilities/vscode-extension-framework/spec.md
index c375113..8d5860c 100644
--- a/src/docs/Capabilities/vscode-extension-framework/spec.md
+++ b/src/docs/Capabilities/vscode-extension-framework/spec.md
@@ -25,7 +25,7 @@ extension inherits a working build-test-release path on day one.
This capability rests on the [Principles](../../Ways-of-Working/Principles/index.md):
- **[Everything as Code](../../Ways-of-Working/Principles/Engineering-Practices.md#everything-as-code).** The pipeline, the version decision, and the extension's configuration are version-controlled workflow and settings — never a GUI action or a hand-run packaging command.
-- **[Decision before change](../../Ways-of-Working/Principles/AI-First-Development.md#decision-before-change).** The pull request is the decision point; its review gate approves the code *and* the release it produces. An owned bump label supplies the level or overrides a configured repository default; the effective decision and its source are recorded.
+- **[Decision before change](../../Ways-of-Working/Principles/AI-First-Development.md#decision-before-change).** The pull request is the decision point; its review gate approves the code *and* the release it produces. An owned bump label overrides the valid effective default, including shared policy and supported caller inputs; the decision and its source are recorded.
- **[Extensible by default](../../Ways-of-Working/Principles/Software-Design.md#extensible-by-default).** The lifecycle is the stable core; host versions, the operating-system matrix, and publish targets are extension-specific settings that slot in. A new publish destination is a configured step, not a new pipeline.
- **[Least-privilege](../../Ways-of-Working/Principles/Purpose-and-Direction.md#least-privilege).** The pipeline runs read-only by default; only the stage that cuts the release holds write, and only the scope it needs.
@@ -55,12 +55,12 @@ framework itself.
## Requirements
- **Opt-in from a template.** A new extension starts from a template repository and inherits the whole pipeline. Adopting the framework is adding a short caller and a settings file, never copying a pipeline into the repo.
-- **A single extension settings file with secure, working defaults.** Extension-specific behavior is configured in one version-controlled settings file. With a valid release decision, zero extension-specific configuration MUST produce a correct build, test, and VSIX. Build and test settings have secure, sensible defaults; the optional release-level default follows Release Management rather than silently choosing a level.
+- **A single extension settings file with secure, working defaults.** Extension-specific behavior is configured in one version-controlled settings file. With a valid release decision, zero extension-specific configuration MUST produce a correct build, test, and VSIX. Build, test, and release settings have documented defaults and supported caller overrides under [Smart defaults, local overrides](../../Ways-of-Working/Principles/Software-Design.md#smart-defaults-local-overrides); the effective release default follows Release Management.
- **A reproducible, self-contained bundle.** The extension is compiled into a single self-contained bundle with no unbundled runtime dependencies; the same commit always produces the same output.
- **Tested on a real host.** The extension is tested against a real VS Code host, across the host versions and operating systems the extension declares as supported. Tests exercise the exact bundle that ships — never a separately compiled copy.
- **A static quality gate.** Every change is linted and type-checked, and the pipeline holds on any error. Quality is validated at pull-request time, not after merge.
-- **Built once, shipped once.** The version is computed once, stamped into the manifest, and the same packaged VSIX is what is tested and what is published. Build, test, and release MUST NOT diverge.
-- **Policy-driven, semantic versioning.** Versioning follows [Release Management](../release-management/spec.md): an explicit owned bump label overrides an optional configured `DefaultBump`; missing or invalid decisions MUST fail the required PR check and block merge. `release:skip` prevents publication, and `release:pre-release` MAY use the resolved explicit or configured bump. The version is [SemVer](https://semver.org/) and is derived automatically — never hand-edited in the manifest.
+- **Built once, shipped once.** The canonical release identity and validated native extension version MUST be resolved before Build. The native version is stamped into the manifest, and the same packaged VSIX is tested and published unchanged. The GitHub Release records the canonical/native mapping; destination-native numbers need not be textually identical. Build, test, and release MUST NOT diverge.
+- **Policy-driven, semantic versioning.** Versioning follows [Release Management](../release-management/spec.md): an explicit owned bump label overrides the valid effective `DefaultBump`; without a bump label, the documented default supplies the level. Invalid settings and conflicting owned labels MUST fail the required PR check and block merge. `release:skip` prevents publication, and `release:prerelease` MAY use the resolved explicit or default bump. The version is [SemVer](https://semver.org/) and is derived automatically — never hand-edited in the manifest.
- **An installable artifact on every release.** Each release produces an installable VSIX attached to its [GitHub Release](https://docs.github.com/en/repositories/releasing-projects-on-github/about-releases), together with an immutable reference. A user MUST be able to install a specific released version without a marketplace account.
- **Optional marketplace publication.** Where configured, the same VSIX is also published to an extension marketplace (the VS Code Marketplace and/or Open VSX). Marketplace publication is opt-in and MUST NOT be a prerequisite for the GitHub-Release install path.
- **A prerelease from an open pull request.** A prerelease VSIX MUST be obtainable from an open pull request for testing before merge, without being promoted to the latest stable version.
@@ -72,10 +72,10 @@ framework itself.
## Success criteria
- Creating a repository from the template and providing a valid release decision yields a green build, a passing test run, and a packaged VSIX with no extension-specific configuration written.
-- An eligible pull request merged to a release branch produces a GitHub Release carrying an installable VSIX whose version matches the explicit or configured bump. Missing decisions, invalid defaults, and conflicting owned labels fail required CI before merge.
+- An eligible merged PR produces a GitHub Release whose canonical version reflects the resolved bump and whose unchanged VSIX uses the recorded native version mapping. Omitting a bump label uses the valid effective default; invalid settings and conflicting owned labels fail required CI before merge.
- The tests that gate the release exercise the exact VSIX that is released, on every supported host version and operating system.
-- A documentation-only or CI-only change carrying `release:skip` runs its checks but produces no new version.
-- A user installs any released version straight from its GitHub Release with no marketplace account; where marketplace publishing is enabled, that same version also appears in the marketplace.
+- On a managed VSIX route, a change outside the artifact/consumer scope carrying `release:skip` runs its checks without publication. An unmanaged route has no release metadata or labels.
+- A user installs any released version from its canonical GitHub Release without a marketplace account; enabled marketplaces publish the unchanged VSIX under its recorded native version/channel mapping.
- An open pull request can publish a prerelease VSIX for testing that never becomes the latest stable version, and it is cleaned up when the pull request closes.
- Adopting the framework in a new extension is a short caller plus a settings file — the pipeline itself is never copied into the repository.
diff --git a/src/docs/Coding-Standards/Dependencies.md b/src/docs/Coding-Standards/Dependencies.md
index 8d106de..bc83265 100644
--- a/src/docs/Coding-Standards/Dependencies.md
+++ b/src/docs/Coding-Standards/Dependencies.md
@@ -44,7 +44,7 @@ The resolution is not to pick a point and freeze — it is to **control integrit
1. **Pin tightly by default** — an identity pin plus a deliberate version, or a lockfile — so every build is reproducible and nothing changes unvetted. A controlled owned-major tag is the narrow exception for automation whose release path the organization or initiative operates.
2. **Automate updates** so currency never depends on a human watching upstream: the [Dependency Updates](../Capabilities/dependency-updates/index.md) bot opens one reviewed pull request per bump.
-3. **Gate every update through CI and review** — every update passes the repository's normal merge policy; security advisories are raised out of band and prioritized. After related changes are collected, decide the repository release bump under [Release Management](../Capabilities/release-management/design.md).
+3. **Gate every update through CI and review** — every update passes the repository's normal merge policy; security advisories are raised out of band and prioritized. After related changes are collected, resolve the repository release decision under [Release Management](../Capabilities/release-management/design.md) when the target route invokes it.
Tight pinning is safe *because* the updates are automated: the bot closes the currency gap and CI plus review close the vetting gap. A controlled owned-major tag applies the same principle at the producer: compatible releases pass the controlled release gate once, then the major pointer rolls them out centrally. It trades consumer-level reproducibility for coordinated rollout and is never valid for an external dependency.
diff --git a/src/docs/Coding-Standards/GitHub-Actions.md b/src/docs/Coding-Standards/GitHub-Actions.md
index dc8c22e..347e8cb 100644
--- a/src/docs/Coding-Standards/GitHub-Actions.md
+++ b/src/docs/Coding-Standards/GitHub-Actions.md
@@ -67,7 +67,8 @@ a fleet of pin-update pull requests.
version comment.
- **Apply the updater's default three-day cooldown** before adopting a freshly published version. Omit an explicit `cooldown` mapping unless the repository deliberately adopts a non-default duration.
- **Make the release decision separately** after dependency changes are
- collected, under [Release Management](../Capabilities/release-management/design.md).
+ collected when the target route invokes [Release
+ Management](../Capabilities/release-management/design.md).
- **Publish owned floating major tags only through controlled release
automation.** The release gate validates compatibility, publishes the immutable
version tag first, and then advances the major tag to that stable release.
diff --git a/src/docs/Coding-Standards/Natural-Language.md b/src/docs/Coding-Standards/Natural-Language.md
index 1e25a7e..2883689 100644
--- a/src/docs/Coding-Standards/Natural-Language.md
+++ b/src/docs/Coding-Standards/Natural-Language.md
@@ -33,7 +33,7 @@ The split is per artifact, not per repository. A repository that serves a Norweg
| `scripts/Test-Link.mjs` | `scripts/Test-Lenker.mjs` |
| `Update-Source.ps1 -Offline` | `Update-Source.ps1 -Frakoblet` |
| `Source not found: ` | `Kilden finnes ikke: ` |
-| `🪲 [Fix]: Broken links no longer reach main` | `🪲 [Fix]: Brutte lenker stoppes` |
+| `Broken links no longer reach main` | `Brutte lenker stoppes` |
Repository artifacts are read by contributors, reviewers, and agents who do not share one first language, and by tooling built for English. Mixed-language automation splinters the vocabulary — `-Frakoblet` and `-Offline` are the same switch — and makes shared standards, linters, and scripts unreusable across repositories.
@@ -76,7 +76,7 @@ Prefer specific, observable language over vague intent.
| Prefer | Avoid |
| --- | --- |
| The workflow fails when the release decision is missing. | There may be some issues with labels. |
-| Add `release:skip` to documentation-only PRs. | Make sure docs PRs are handled correctly. |
+| On a release-managed route, add `release:skip` when documentation does not affect the artifact. | Make sure docs PRs are handled correctly. |
| The agent reads `AGENTS.md` before editing files. | The agent should probably look at the instructions. |
Use **MUST**, **SHOULD**, and **MAY** only when a sentence is intentionally normative. If a rule is optional, say what trade-off decides it.
@@ -154,7 +154,7 @@ A good error message includes:
Prefer:
```text
-Release decision is missing. Add a release:patch, release:minor, or release:major label, configure DefaultBump in the release settings, or select release:skip. Prerelease mode still requires a resolved bump. This required CI check must pass before merge.
+Release decision cannot be resolved for this managed route. Correct the invalid DefaultBump setting or conflicting release labels. A valid effective default supplies the bump without a per-PR bump label; one release:patch, release:minor, or release:major label overrides it, and release:skip selects no release. Prerelease mode uses release:prerelease and the resolved bump. This required CI check must pass before merge.
```
Avoid:
@@ -169,10 +169,11 @@ PR titles and descriptions are written for the user of the change first, then th
| Prefer | Avoid |
| --- | --- |
-| `📖 [Docs]: Agentic development framework documented` | `Update framework docs` |
+| `Agentic development guidance defines the framework` | `Update framework docs` |
| `Agents segment project context before loading standards.` | `Refactor AGENTS.md instructions.` |
-Technical implementation details belong in a clearly named technical section at the bottom of the PR body.
+Technical implementation details belong in the `Technical details` block for
+the reader-facing result they support.
## Prompts
diff --git a/src/docs/Ways-of-Working/Automation-Labels.md b/src/docs/Ways-of-Working/Automation-Labels.md
index 83b792a..fd3b443 100644
--- a/src/docs/Ways-of-Working/Automation-Labels.md
+++ b/src/docs/Ways-of-Working/Automation-Labels.md
@@ -53,18 +53,27 @@ namespaced, including the release set:
| `release:patch` | Publish a patch release. |
| `release:minor` | Publish a minor release. |
| `release:major` | Publish a major release. |
-| `release:pre-release` | Publish a prerelease from the open pull request. |
+| `release:prerelease` | Publish a prerelease from the open pull request. |
| `release:skip` | Validate the change without publishing a release. |
+This set applies only when the pull request's target route invokes Release
+Management, including through a native producer pipeline. An unmanaged route
+does not apply or report any
+`release:*` label, including `release:skip`. The optional
+`.github/release.config.yml` file refines an invocation; its absence alone does
+not determine whether the route invokes the capability.
+
These labels are read by
[release management](../Capabilities/release-management/spec.md) and by nothing else.
-One owned bump label records an explicit level and overrides the optional
-repository `DefaultBump`; for publishing decisions without a bump label, a valid
-configured default supplies it. `release:skip` records a no-release decision.
-`release:pre-release` is a mode used with a resolved explicit or configured bump,
+One owned bump label records an explicit level and overrides the valid effective
+`DefaultBump`; without a bump label, documented defaults, repository settings,
+and supported caller overrides supply it. `release:skip` records a no-release decision.
+`release:prerelease` is a mode used with a resolved explicit or default bump,
never with `release:skip`. Release Management owns the
[resolver and required pre-merge validation](../Capabilities/release-management/design.md#version-computation);
-an absent label and absent default are not an implicit patch decision.
+an omitted setting inherits the documented patch default, while invalid settings
+and conflicting owned labels fail rather than select a fallback. Settings, not
+additional release labels, select configured release-candidate and announcement behavior.
Reserving bare words would be weaker because it depends on a documented
prohibition rather than making ownership visible in the label itself.
diff --git a/src/docs/Ways-of-Working/Branching-and-Merging.md b/src/docs/Ways-of-Working/Branching-and-Merging.md
index cc2bdf6..b71c1d6 100644
--- a/src/docs/Ways-of-Working/Branching-and-Merging.md
+++ b/src/docs/Ways-of-Working/Branching-and-Merging.md
@@ -35,7 +35,7 @@ Every layer follows the ordinary [Contribution Workflow](Contribution-Workflow.m
1. **Plan the dependency.** Give each layer its own Task or Bug issue. Add a native blocked-by edge from every dependent leaf to its prerequisite as described in [Issue Relationships](Issues/Process/Relationships.md#execution-order); prose, sub-issue order, and stack position do not create the gate.
2. **Open every layer as a draft.** After the initial commit, push the branch and open its pull request immediately. Use the standard user-facing title and description from [PR Format](PR-Format.md); do not add stack position or an internal branch name to the title.
-3. **Link the stack in Technical Details.** Add fully qualified pull request links for the immediate dependency and dependent, using `Depends on Owner/Repo#N` and `Followed by Owner/Repo#N`. Each pull request closes only its own Task or Bug.
+3. **Link the stack in Related references.** Add fully qualified pull request links for the immediate dependency and dependent to the applicable section's `Related references` block, using `Depends on Owner/Repo#N` and `Followed by Owner/Repo#N`. Each pull request closes only its own Task or Bug.
4. **Keep each delta isolated.** The pull request diff against its current base contains only that layer's change. Run its tests, checks, and automated review even when an earlier layer already exercised the combined code.
5. **Make one layer ready at a time.** Only the lowest unmerged layer is marked ready and given auto-merge. Every later layer stays draft, even when its current checks are green.
6. **Advance after merge.** When the lowest layer lands, refresh the next branch against the landed target, retarget its pull request to that target, and verify that the diff still contains only its intended change. Run CI and the automated review loop again before marking it ready.
@@ -59,7 +59,7 @@ A repository on the promotion model MAY keep a **standing draft pull request** f
- **One long-lived pull request, not one per promotion.** Merging it promotes; a new draft opens immediately, so the candidate view is never absent.
- **Draft is the resting state.** It is marked ready when the integrated state is deemed promotable, which is what turns review and any promotion gate on.
- **Its description is the promotion note.** Assembled from the changes it carries, it is the record of what a promotion contained, written for whoever operates the destination.
-- **Its resolved release decision determines the production version.** Promotion is a release like any other, so the level comes from this pull request's explicit bump label or the configured repository default, not from the versions of the changes it bundles ([release management](../Capabilities/release-management/spec.md)).
+- **Its release metadata follows the target route.** When the route invokes [Release Management](../Capabilities/release-management/spec.md), the pull request's `Release decisions` block records the production decision and the level comes from its explicit owned bump label or the valid effective `DefaultBump`, including shared defaults, repository settings, and supported caller overrides, not from the versions of the changes it bundles. A route without that invocation omits the block and all `release:*` labels.
The value is continuous visibility: at any moment, the difference between what is integrated and what is live is one link. It suits repositories where promotion is a deliberate, gated event and costs more than it returns where every merge already ships.
diff --git a/src/docs/Ways-of-Working/Continuous-Delivery-And-Release.md b/src/docs/Ways-of-Working/Continuous-Delivery-And-Release.md
index aaa7432..3b82987 100644
--- a/src/docs/Ways-of-Working/Continuous-Delivery-And-Release.md
+++ b/src/docs/Ways-of-Working/Continuous-Delivery-And-Release.md
@@ -86,15 +86,23 @@ guarantee instead.
### D2 — Version signals feed in, the decision is reviewed at the PR gate {#d2-version-signals-feed-in-the-label-decides-at-the-pr-gate}
+This decision protocol applies only to actual Release Management routes,
+including native producer pipelines. An unmanaged route has no release-decision
+block, `release:*` labels, or missing-decision check; continuous delivery alone
+does not opt it into a versioned release process.
+
Several signals suggest what kind of change a pull request contains: the shape of the
diff, whether tests were added or changed, the commit messages, and an AI-assisted
reading of the change. Those signals MUST be treated as input. The
[resolved release decision](../Capabilities/release-management/design.md#version-computation)
-comes from an explicit owned label or the repository's configured default, and
+comes from an explicit owned bump label or the valid effective `DefaultBump`, and
its suitability for the audience is reviewed at the pull-request gate.
-A configured default is a prior policy decision, not an omission to interpret
-later. The pull request records the effective level and its source, and review
+A documented default is a prior policy decision, not an omission to interpret
+later. Repository settings and supported caller inputs can override it; an
+explicit owned bump label overrides the valid effective default. Invalid
+supplied settings and conflicting owned labels fail rather than use a fallback.
+The pull request records the effective level and its source, and review
confirms that the level fits the declared user/integrator impact. A missing
decision fails a required CI check and blocks merge; publication
does not discover the missing decision only after integration.
diff --git a/src/docs/Ways-of-Working/Contribution-Workflow.md b/src/docs/Ways-of-Working/Contribution-Workflow.md
index 9809968..1cd8f4e 100644
--- a/src/docs/Ways-of-Working/Contribution-Workflow.md
+++ b/src/docs/Ways-of-Working/Contribution-Workflow.md
@@ -34,10 +34,15 @@ flowchart TD
that delivery issue and the pull request, not in the spec, design, or parent
aggregate.
2. **Open the pull request as a draft.** A draft attaches CI and keeps the change
- out of people's review queues while you iterate.
+ out of people's review queues while you iterate. Assign the pull request to
+ its author and apply any repository-owned workflow labels.
3. **Run the Copilot review loop** (below) until Copilot reports a clean round —
no changes requested and no new inline comments.
-4. **Mark the pull request ready for review** once it meets the
+4. **Finalize and mark the pull request ready for review.** Re-read the complete
+ diff and finalize the title and description per [PR Format](PR-Format.md).
+ If the target route invokes Release Management, reconcile the conditional
+ decision block and `release:*` labels with its effective configuration. If it
+ does not, omit both. Then confirm the
[Definition of Ready for Review](Definition-of-Ready-and-Done.md#definition-of-ready-for-review).
5. **Enable auto-merge** so the change lands automatically when human review
approves and the required checks stay green. Human review takes over from there.
@@ -121,7 +126,8 @@ the approval identity that satisfies the gate.
- [Workflow](Workflow.md) — the spec-led loop this operates within.
- [Issue Lifecycle](Issues/Process/Lifecycle.md) — why only ready Task and Bug leaves enter this flow.
-- [PR Format](PR-Format.md) — the pull request title, description, and labels.
+- [PR Format](PR-Format.md) — the pull request title, description, and
+ route-conditional release metadata.
- [Definition of Ready and Done](Definition-of-Ready-and-Done.md#definition-of-ready-for-review) — the readiness gate this hands off at.
- [Branching and Merging](Branching-and-Merging.md) — the branch model a pull request builds on.
- [Review Etiquette](Review-Etiquette.md) — how human review proceeds once the pull request is ready.
diff --git a/src/docs/Ways-of-Working/Definition-of-Ready-and-Done.md b/src/docs/Ways-of-Working/Definition-of-Ready-and-Done.md
index c68b48b..fe00242 100644
--- a/src/docs/Ways-of-Working/Definition-of-Ready-and-Done.md
+++ b/src/docs/Ways-of-Working/Definition-of-Ready-and-Done.md
@@ -33,7 +33,7 @@ A pull request is ready for review when:
- The automated review loop has converged — a clean [Copilot round](Contribution-Workflow.md#the-copilot-review-loop) with no unresolved review threads.
- The [standards and framework alignment pass](Workflow-Stages/Implement.md#5-standards-and-framework-alignment-pass) has run against the finished change, its result covers every changed surface in the pull request, and every exception links a follow-up issue.
- The [issue convergence sweep](Workflow-Stages/Implement.md#6-issue-convergence-sweep) has run against scoped open issues, and every fully convergent issue is linked in the pull request with a closing keyword.
-- The title, release-note description, and effective release decision and its source are finalized per [PR Format](PR-Format.md). Where Release Management applies, its [required decision check](../Capabilities/release-management/design.md#required-pre-merge-decision-check) passes; an explicit label is not mandatory when a valid configured default supplies the level.
+- The title and release-note-ready description are finalized per [PR Format](PR-Format.md). When the target route invokes Release Management, the `Release decisions` block, effective configuration, and applied `release:*` labels agree, and the [required decision check](../Capabilities/release-management/design.md#required-pre-merge-decision-check) passes; an explicit bump label is not mandatory when the valid effective default supplies the level, including supported caller overrides. When the route does not invoke Release Management, the block and labels are absent.
Absent checks are not a pass. When a pull request reports no checks at all, the usual cause is that the workflow's triggers do not cover it — a base branch outside the `pull_request` trigger's `branches` filter is the common one — and that is a gap to fix or file, not a gate to wave through. Manually dispatching the workflow against the branch does not substitute for it either: jobs gated on the event type are skipped silently, so a green `workflow_dispatch` run can hide verification that never ran. If the checks genuinely cannot be made to run before merge, say so in the pull request and link the issue tracking it, so the reviewer knows the gate was not met instead of assuming it was.
diff --git a/src/docs/Ways-of-Working/Documentation-Model.md b/src/docs/Ways-of-Working/Documentation-Model.md
index 6f53dbb..9bd9c2c 100644
--- a/src/docs/Ways-of-Working/Documentation-Model.md
+++ b/src/docs/Ways-of-Working/Documentation-Model.md
@@ -105,6 +105,7 @@ with no reader, so a folder appears the first time it has something to hold
| **How the work is done** — process, principles, conventions | [Ways of Working](index.md) |
| **How code looks** — style applied to code | [Coding Standards](../Coding-Standards/index.md) |
| **How this one change is implemented** — paths, trade-offs | the Task or Bug delivery leaf and its PR; see [Issue Planning](Issues/Process/Planning.md) |
+| **What a release changes, why, and how consumers align** | its source-bound release record, authored in the release-bound PR; see [PR Format](PR-Format.md) |
Keeping implementation out of the spec is what makes the spec durable:
implementation detail rots fastest, so the spec leaves it to the design, the
@@ -149,8 +150,9 @@ history records what changed; the document records only what is true now.
trusts any line as the current contract.
- **Normative.** Requirements use MUST / SHOULD / MAY so obligations are
unambiguous.
-- **No status, deltas, phasing, or open questions.** Those rot the moment they
- are written; they belong in issues, PRs, and git history.
+- **No status, deltas, phasing, or open questions.** Delivery plans belong in
+ issues and PRs; release-specific changes and adoption instructions belong in
+ release records.
- **Measurable success criteria.** A spec states outcomes a reader can verify —
*"a repository list returns every repository by default, with no silent
truncation"* — never *"the sync is fast."*
@@ -160,6 +162,27 @@ requirement testable, are criteria measurable and implementation-free, is it
present-tense and free of status? — applied in the reviewer's head and the PR
([4-eyes](Principles/AI-First-Development.md#4-eyes-or-n-eyes-principle)), leaving no artifact behind.
+### Current product guidance and release history
+
+Resource docs, including READMEs, specs, designs, implementation docs, guides,
+and references, describe supported target-state behavior and usage for their
+readers. Update them in place as that contract changes. Keep release-specific
+old-to-new transitions, migration instructions, and change history in the
+[release records](../Capabilities/release-management/design.md#release-notes),
+not a parallel history file or migration-guide hierarchy.
+
+Release notes explain what changed, why, who is affected, compatibility, and
+exact applicable adoption actions or an explicit no-action result. Reading all
+applicable records after the actual consumed baseline through the target is
+sufficient to compose the required upgrade actions; PRs and diffs provide
+optional depth. General upgrade procedures may explain how to use those
+records, without becoming another source of release-specific instructions.
+
+Decision records and research retain their distinct purposes: decisions preserve
+the choices, rationale, and supersession links, while research preserves
+point-in-time findings. Keeping resource docs evergreen does not erase these
+records.
+
## Concise by default
Respect the reader's attention — human or agent. A document earns nothing by
diff --git a/src/docs/Ways-of-Working/Fleet-Orchestration.md b/src/docs/Ways-of-Working/Fleet-Orchestration.md
index ed34da6..475c150 100644
--- a/src/docs/Ways-of-Working/Fleet-Orchestration.md
+++ b/src/docs/Ways-of-Working/Fleet-Orchestration.md
@@ -36,10 +36,13 @@ tool, can read and drive a campaign with the GitHub CLI alone.
A campaign is one change rolled out across a set of repositories. Each
repository's slice is one Task or Bug delivery leaf and its pull request. A
campaign has a short, stable **slug** (for example `process-psmodule-v6`) that
-names both artifacts everywhere.
+prefixes every delivery issue. A campaign pull request carries that identity
+through its native Development link to the prefixed issue, leaving the pull
+request title free for its reader-facing result. A closing keyword creates that
+link only when the pull request targets the repository's default branch.
An **existing open pull request can be adopted** when its scope matches the
-campaign slice. Ensure it closes exactly one correctly typed Task or Bug,
+campaign slice. Link it to exactly one correctly typed Task or Bug,
creating that delivery issue first when it is missing, then add the remaining
change to the existing branch instead of opening a duplicate. Reusing what is
already open avoids competing pull requests without bypassing the canonical
@@ -65,18 +68,34 @@ copied into another state-bearing field, because duplicated state drifts.
| Review outcome | `reviewDecision` and unresolved review threads |
| Mergeability | `mergeable` / merge-state status |
| Done | pull request **merged**; Task or Bug **closed** |
-| Issue ↔ PR link | the pull request's one closing reference |
+| Issue ↔ PR link | the native Development link; a supported default-branch closing reference or an explicit manual link |
-"Ready for review" is the draft flag flipping off; "done" is the merge. The two
-signals people care about most are native, and are set by the same act that does
-the work — [marking ready](Contribution-Workflow.md) and merging.
+"Ready for review" is the draft flag flipping off; "Merged" is the pull request's
+merge state. Delivery completion also requires the Task or Bug to close after
+its recorded Done gate. These are native signals, not copied stage fields.
-### Campaign identity lives in the title
+### Campaign identity lives on the delivery issue
Campaign membership is carried in a stable square-bracket prefix on every
-delivery issue and pull request title, for example `[process-psmodule-v6]`. The
-prefix is the cross-repository join key; labels stay reserved for mutable
-workflow state.
+delivery issue title, for example `[shared-workflow-alignment]`. Each campaign
+pull request is natively linked to exactly one of those issues, so the
+Development relationship joins it to the campaign without copying internal metadata into
+its title. Labels stay reserved for mutable workflow state.
+
+### Link and close for the actual target
+
+For a default-branch target, use the scoped closing reference from [PR
+Format](PR-Format.md). For a non-default target, explicitly link the pull request
+and delivery issue through GitHub's **Development** sidebar and verify the native
+link; description closing keywords are ignored on those targets. See
+[GitHub's linking rules](https://docs.github.com/en/issues/tracking-your-work-with-issues/using-issues/linking-a-pull-request-to-an-issue).
+
+A non-default merge does not close the issue automatically. Keep the delivery
+issue open until its recorded [Definition of Done](Definition-of-Ready-and-Done.md#repository-delivery-leaf)
+holds, including any required default-branch integration or publication. The
+recorded completion owner then verifies the evidence and closes it explicitly,
+or links the completed delivery to a qualifying default-branch integration PR.
+Never close it merely to make the dashboard show Done.
### Process labels fill the gap
@@ -91,11 +110,13 @@ same way.
| `stage:in-progress` | Actively being changed; the assignee owns it. |
| `stage:blocked` | Needs a human decision or a manual, off-platform action before it can proceed. |
-Rules: the campaign prefix is mandatory on every delivery issue and pull request; at most one
-`stage:*` label applies at a time; and `stage:*` may be dropped once a pull
-request carries the signal itself (a ready pull request needs no `stage` label,
-but `stage:blocked` stays explicit because "a human must act" has no built-in
-equivalent). The slug inside the prefix is lowercase and hyphenated.
+Rules: the campaign prefix is mandatory on every delivery issue; each campaign
+pull request is natively linked to one prefixed issue and uses the reader-facing title from [PR
+Format](PR-Format.md) without the prefix; at most one `stage:*` label applies at
+a time; and `stage:*` may be dropped once a pull request carries the signal
+itself (a ready pull request needs no `stage` label, but `stage:blocked` stays
+explicit because "a human must act" has no built-in equivalent). The slug inside
+the issue prefix is lowercase and hyphenated.
## Effective status
@@ -135,21 +156,22 @@ flowchart TD
```
1. **Queue the work.** Create one Task or Bug delivery issue per repository, with
- the campaign prefix in the title and `stage:queued`. Route it through the
- [Issue Hierarchy](Issues/Types/Hierarchy.md) and follow its canonical type
- page. The whole fleet starts as *Queued*.
+ the campaign prefix in the title and `stage:queued`. Route it through the
+ [Issue Hierarchy](Issues/Types/Hierarchy.md) and follow its canonical type
+ page. The whole fleet starts as *Queued*.
2. **Branch and open a draft.** Create a worktree and branch
- ([Git Worktrees](Git-Worktrees.md)), then open a **draft** pull request that
- closes exactly that delivery issue, per [PR Format](PR-Format.md). Use the same
- campaign prefix in the pull request title and move the stage to
- `stage:in-progress`, clearing the issue's `stage:queued` so the repository
- delivery never carries two stages at once. If the repository already has an open
- pull request that covers part of the change, adopt it instead of opening a
- new one: add the remaining change to its branch, return it to **draft** while
- work is in progress, and give it the same campaign prefix and
- `stage:in-progress` label (clearing `stage:*` from its closing issue). Add the
- one closing Task or Bug reference before continuing if the adopted pull
- request did not already have it.
+ ([Git Worktrees](Git-Worktrees.md)), then open a **draft** pull request natively
+ linked to exactly that prefixed delivery issue, per [PR Format](PR-Format.md)
+ and the target-specific linking rules above.
+ The Development link carries campaign membership, so the pull request title
+ states only its reader-facing result. Move the stage to `stage:in-progress`,
+ clearing the issue's `stage:queued` so the repository delivery never carries
+ two stages at once. If the repository already has an open pull request that
+ covers part of the change, adopt it instead of opening a new one: add the
+ remaining change to its branch, return it to **draft** while work is in
+ progress, and give it `stage:in-progress` (clearing `stage:*` from its delivery
+ issue). Verify its native link to the prefixed Task or Bug before continuing
+ if the adopted pull request did not already have one.
3. **Apply the change and run the loop.** Make the change and take the pull
request through the [Contribution Workflow](Contribution-Workflow.md) —
the Copilot review loop — exactly as any single-repository change. The
@@ -162,8 +184,9 @@ flowchart TD
and CI is green, mark the pull request ready for review per the
[Definition of Ready and Done](Definition-of-Ready-and-Done.md). The draft
flag flips and the repository delivery becomes *Ready for review*.
-6. **Human review and merge land it.** Merging lands the change and closes its
- Task or Bug through the pull request's one closing reference.
+6. **Human review and merge land it.** Merging lands the change. A qualifying
+ default-branch closing reference closes its Task or Bug automatically;
+ non-default delivery follows the recorded completion and closure rules above.
The campaign's job is to get every pull request to *Ready*;
[Branching and Merging](Branching-and-Merging.md) governs how it merges.
@@ -215,10 +238,28 @@ identical diff.
A campaign is watched through a **dashboard** — a deterministic projection of
GitHub state, not a store of its own. A script enumerates the campaign's
-repository deliveries by title prefix (`[]` across the owners), reads each pull request's
-built-in properties, computes the effective status, and renders a page. It can
-regenerate on an interval so the view refreshes as GitHub changes; deleting it
-loses nothing, because GitHub is the source of truth.
+delivery issues by title prefix (`[]` across the owners), follows each
+native Development link to its pull request, reads the built-in properties,
+computes the effective status, and renders a page. It can regenerate on an
+interval so the view refreshes as GitHub changes; deleting it loses nothing,
+because GitHub is the source of truth.
+
+Read linked pull requests with full pagination and include closed or merged
+ones. `closedByPullRequestsReferences` retrieves closing associations, not every
+manual Development link. Also read the issue's native `ConnectedEvent` and
+`DisconnectedEvent` timeline entries, including both source and subject.
+Fold those entries in returned timeline order for each issue–PR pair: a
+connection adds the manual association and a disconnection removes it. Keep only
+pairs with the queried issue's node ID at one endpoint and a PR at the other;
+use PR node IDs, not display numbers, as the identity. Combine
+the current manual associations with closing references, deduplicate by PR
+identity, then read each PR's live state. Ordinary prose cross-references do not
+replace a verified Development association.
+
+Verify explicit links for non-default targets rather than reconstructing
+them from ignored keywords or assuming the closing-reference query is complete.
+A missing or unreadable link on an in-progress
+delivery is a discovery gap to report, not an empty or completed delivery.
Typical columns: effective status, repository, delivery issue and pull request, draft/ready,
CI, review decision and open-thread count, assignee, the latest progress note,
@@ -244,11 +285,12 @@ a deterministic label-and-comment write, so it is scripted; the judgement of
Because all state is on GitHub and the workflow labels are generic:
- **A person** can run a whole campaign from the GitHub UI — filter by
- the campaign prefix in the title, read each pull request's draft and merge state, move
- `stage:*` labels, and merge.
+ the campaign prefix in delivery issue titles, follow each issue's linked pull
+ request, read its draft and merge state, move `stage:*` labels, and merge.
- **An automated system** — a scheduled workflow, a different agent framework, or
- a teammate's tooling — can enumerate the work with one query and pick up any
- delivery. The state is portable and self-describing.
+ a teammate's tooling — can enumerate the issues with one query, follow their
+ native pull request references, and pick up any delivery. The state is
+ portable and self-describing.
If an automated run stops midway, nothing is lost: the board is complete, every
in-flight pull request shows its true state, and anyone can finish the job. This
@@ -261,9 +303,61 @@ hand. Labels and comments use the issues API, which serves issues and pull
requests alike.
```powershell
-# enumerate a campaign's pull requests across an owner
-gh search prs 'in:title "[]"' --owner `
- --json number,repository,title,url,isDraft,state
+# enumerate a campaign's delivery issues across an owner
+gh search issues 'in:title "[]"' --owner `
+ --json number,repository,title,url,state
+
+# read closing associations, including closed/merged PRs, with full pagination
+$query = @'
+query($owner: String!, $repo: String!, $number: Int!, $endCursor: String) {
+ repository(owner: $owner, name: $repo) {
+ issue(number: $number) {
+ closedByPullRequestsReferences(first: 100, after: $endCursor, includeClosedPrs: true) {
+ nodes { id number url state }
+ pageInfo { hasNextPage endCursor }
+ }
+ }
+ }
+}
+'@
+gh api graphql --paginate -f query="$query" -f owner='' -f repo='' -F number=''
+
+# read manual Development associations separately; fold connect/disconnect pairs
+$developmentQuery = @'
+fragment DevelopmentSubject on ReferencedSubject {
+ __typename
+ ... on Issue { id url }
+ ... on PullRequest { id number url }
+}
+query($owner: String!, $repo: String!, $number: Int!, $endCursor: String) {
+ repository(owner: $owner, name: $repo) {
+ issue(number: $number) {
+ id
+ timelineItems(
+ first: 100
+ after: $endCursor
+ itemTypes: [CONNECTED_EVENT, DISCONNECTED_EVENT]
+ ) {
+ nodes {
+ __typename
+ ... on ConnectedEvent {
+ createdAt
+ source { ...DevelopmentSubject }
+ subject { ...DevelopmentSubject }
+ }
+ ... on DisconnectedEvent {
+ createdAt
+ source { ...DevelopmentSubject }
+ subject { ...DevelopmentSubject }
+ }
+ }
+ pageInfo { hasNextPage endCursor }
+ }
+ }
+ }
+}
+'@
+gh api graphql --paginate -f query="$developmentQuery" -f owner='' -f repo='' -F number=''
# read one pull request's authoritative state
gh pr view --repo / --json `
@@ -278,26 +372,30 @@ gh api -X POST repos///issues//comments -f body=""
gh pr ready --repo /
```
-## Worked example: Process-PSModule and Pester 6
+## Worked example: A shared workflow upgrade
-A concrete campaign from the [PSModule](../Initiatives/PSModule.md) initiative:
-adopt the latest Process-PSModule reusable workflow across every consumer, add
-the Pester version requirement to the test files, and migrate the tests.
+A campaign aligns consumers with one fixed producer release. Its release records
+own the version-specific migration actions; this general procedure does not
+invent or duplicate them.
-- **Slug:** `process-psmodule-v6`.
+- **Slug:** `shared-workflow-alignment`.
- **Discover the fleet:** find consumers of the reusable workflow with a code
search for its `uses:` reference, then queue a Task delivery issue in each.
-- **Per repository:** bump the workflow pin, add the
- `#Requires -Modules @{ ModuleName = 'Pester'; ModuleVersion = '6.0.0'; MaximumVersion = '6.*' }`
- requirement to each `*.Tests.ps1`, migrate the tests, and take the pull request
- through the [Contribution Workflow](Contribution-Workflow.md).
-- **Track it:** every issue and pull request starts with `[process-psmodule-v6]`;
- the dashboard shows the fleet advancing from *Queued* to *Merged*.
+- **Per repository:** establish its actual consumed baseline and fixed target,
+ read every applicable source-bound release record, compose the required
+ actions and intermediate operations, preserve local intent, and verify the
+ result with its existing checks. A required instruction missing from the
+ records blocks that delivery.
+- **Track it:** every delivery issue starts with `[shared-workflow-alignment]`;
+ each pull request uses a reader-facing title and a verified native issue link.
+ Default-branch closing keywords and explicit non-default linking follow the
+ target-specific rules above. The dashboard retains both live and merged PRs.
## What this is not
- **Not a database.** Any `JSON` or `HTML` is a disposable projection of GitHub.
- **Not agent-specific.** The model stays fully operable by people and non-agent
tools; nothing in it depends on a particular assistant.
-- **Not a shared label store.** Labels are per-repository; the campaign title
- prefix is the shared contract, created in each participating repository.
+- **Not a shared label store.** Labels are per-repository; the delivery-issue
+ prefix plus the native Development link is the shared contract in each
+ participating repository.
diff --git a/src/docs/Ways-of-Working/PR-Format.md b/src/docs/Ways-of-Working/PR-Format.md
index 72f1174..ffb444b 100644
--- a/src/docs/Ways-of-Working/PR-Format.md
+++ b/src/docs/Ways-of-Working/PR-Format.md
@@ -1,321 +1,640 @@
---
title: PR Format
-description: Pull request title, description, change types, and labels.
+description: Audience-first pull request titles and descriptions with evidence-based, conditional release decisions.
---
# PR Format
-Pull requests in the MSX ecosystem double as **release notes**. Write for end users, including downstream integrators: what changes, who is affected, and how to adopt it. Keep consumer instructions distinct from reviewer and maintainer evidence.
-
-## The source of truth
-
-The release-bound PR title and complete description are the authored release note. The contract lives in structured Markdown in that body, not a parallel JSON/YAML file or a version-specific migration guide. [Release Management](../Capabilities/release-management/design.md#release-notes) owns publication, resolved release coordinates, provenance, and traceable corrections.
-
-Describe the **incremental change introduced by this release**, not a migration manual from every previous version. Consumers compose the applicable records across their upgrade range; a note for the newest release does not replace the intervening evidence.
-
-## Title
+A pull request title and description are release-note-ready artifacts. They
+explain one complete change to the people who use what the repository delivers,
+while carrying the evidence reviewers and maintainers need.
+
+The release-bound title and complete description author the eventual release
+note. Published release records are the consumer's sufficient upgrade history:
+what changed, why, who is affected, compatibility, and exactly how to adopt each
+release, including an explicit no-action result when applicable. PRs and diffs
+provide optional depth, not required instructions missing from the notes.
+
+Consumers read every applicable release after their actual consumed baseline
+through the chosen target in release order and compose the necessary actions.
+Reading those records does not require installing every intermediate version;
+an intermediate installation or run is required only when a note explicitly
+requires it. [Resource documentation](Documentation-Model.md#current-product-guidance-and-release-history)
+describes supported target-state behavior and usage, not release-specific
+transitions or history.
+
+This page owns the title and description format. The
+[Contribution Workflow](Contribution-Workflow.md) owns draft, assignment,
+review, and handoff mechanics; [Branching and Merging](Branching-and-Merging.md)
+owns branches, commits, and integration.
+
+## Analyze before writing
+
+Write from evidence, not from the branch name, commit messages, or the existing
+pull request text. Those surfaces are useful leads, but the complete change is
+the source.
+
+### Identify the readers
+
+Start with the repository [README audience
+declaration](Readme-Driven-Context.md#target-audience), then inspect linked user
+documentation, capability specifications, and effective configuration.
+
+Treat every supported interface as reader-facing when someone depends on it.
+Commands, APIs, configuration, reusable workflows, Actions, templates, and
+published guidance can all be the product. Do not classify an integration as
+internal merely because its readers write scripts or maintain another product.
+
+For documentation-only work, the delivered result is guidance. State what a
+reader can now understand or do; do not present documentation as product
+behavior that the change did not implement.
+
+### Read the whole change
+
+Inspect the complete base-to-head diff before writing. For a release-bound
+record, reconcile the complete delivered change since its identified
+release/source baseline, including earlier merged or skipped changes in that
+range. A promotion or bundled release must retain every applicable consumer
+delta, not just the latest commit or pull request.
+
+Check claims against the changed public interfaces, documentation,
+configuration, tests, and generated output. Commit messages and an earlier pull
+request description may be incomplete or stale and never replace this check.
+
+### Keep claims accurate
+
+State only outcomes the evidence supports:
+
+- Describe a dependency update's behavior or security benefit only when upstream
+ notes, tests, or product evidence establish that result.
+- Describe documentation work as changed guidance unless the same change also
+ changes the documented product.
+- Distinguish a public contract change from the internal implementation that
+ delivers it.
+- Check affected supported uses for compatibility, prerequisites, and exact
+ adoption actions, including required ordering or intermediate operations.
+- State an explicit no-action result and its compatibility basis when adoption
+ needs no consumer change beyond selecting the release reference.
+- Treat missing applicability or migration instructions as an evidence gap to
+ resolve in the note, not a reason to send consumers to PRs, diffs, or
+ historical product docs.
+
+### Resolve release decisions
+
+Before adding release metadata or changing a `release:*` label, determine
+whether the repository invokes [Release
+Management](../Capabilities/release-management/spec.md) for the pull request's
+target route. Inspect the effective pipeline and its inputs, including native
+producer pipelines that publish versioned artifacts without calling a named
+shared workflow. The [applicability contract](../Capabilities/release-management/design.md#applicability)
+is about the route's release behavior, not one implementation. The optional
+`.github/release.config.yml` file refines the route's settings; its absence alone
+does not prove that release management is absent.
+
+Verify the immutable producer revision's supported settings and owned-label
+mapping before using the canonical signals below. A native producer participates
+in the contract but does not gain support for those signals from this
+documentation alone. If its released interface differs, require a verified
+adapter or a producer/configuration migration with complete adoption actions in
+that producer's PR/release record. Hold finalization until the effective mapping
+and required decision check are verified; do not apply a label the pipeline
+ignores, silently translate it, or classify an incompatible producer as unmanaged.
+
+If the route does not invoke Release Management, omit the entire `Release
+decisions` block and do not apply or report any `release:*` label, including
+`release:skip`.
+
+If the route does invoke Release Management, resolve these decisions from the
+complete change and the effective
+[configuration](../Capabilities/release-management/design.md#configuration-surface):
+
+1. **Release or skip.** Release when the change affects the versioned artifact
+ or a supported consumer contract. Otherwise select `release:skip`.
+2. **Version bump.** For a release, choose Patch, Minor, or Major from the
+ compatibility impact. An explicit bump label overrides a valid
+ effective `DefaultBump`; a matching default supplies the level without a
+ per-PR bump label. Resolve the documented shared default, repository settings,
+ and supported caller overrides under
+ [settings and caller overrides](../Capabilities/release-management/design.md#settings-and-caller-overrides).
+3. **Mode.** Record Stable or Prerelease from the target route and any valid
+ `release:prerelease` override. Identify a configured release-candidate route
+ in the mode evidence; release candidates are prereleases, not another bump.
+
+Use only the labels owned by the
+[`release:` namespace](Automation-Labels.md#every-set-is-namespaced). Missing,
+invalid, or conflicting decisions are errors to resolve before review, not
+reasons to invent a fallback. Inheriting the documented patch default is a valid
+decision source, not an error recovery path.
+
+### Select the news
+
+Keep the summary and named sections focused on results that matter to the
+identified readers without omitting a consumer delta or required action. Put
+implementation facts, validation, and process evidence in supporting details.
+Omit internal facts that neither explain a reader-facing result nor help review
+it.
+
+Internal-only work can still have a clear result, such as a shared automation
+configuration. When it has no reader-facing classified section, summarize the
+result and put necessary supporting blocks directly after the summary marker.
+
+### Group related changes
+
+Group changes by audience-facing result or affected interface, not by commit,
+file, issue, or implementation step. One section may describe several files
+that jointly deliver one result. Separate unrelated reader outcomes into their
+own sections and classify each result once.
+
+## Write the title
+
+Use one short statement of the most important user-facing result:
```text
- []:
+LLM Gateway streaming requests report usage
```
-- The **Icon** matches the change type.
-- The **Type** in brackets is one of: `Major`, `Feature` (Minor), `Patch`, `Fix`, `Docs`, `Maintenance`.
-- The **outcome** describes what changed from the end user's perspective. Do not lead with private function or class names or refactoring verbs; public commands, inputs, APIs, paths, and settings are consumer-facing concepts.
-
-### Good titles
+For internal-only work, name the operational result:
-- `🌟 [Major]: Legacy export command removed`
-- `🚀 [Feature]: Custom templates now supported`
-- `🩹 [Patch]: Default timeout value corrected`
-- `🪲 [Fix]: Parameter validation no longer fails on null input`
-- `📖 [Docs]: Installation guide updated with prerequisites`
-- `⚙️ [Maintenance]: Internal build tooling stays current`
-
-### Bad titles
-
-- `Add support for custom templates` — describes the action, not the outcome.
-- `Refactor parameter validation logic` — implementation language.
-- `Update stuff` — meaningless.
+```text
+Release automation uses a shared configuration
+```
-## Change types
+The title must not contain:
-| Type | Icon | Label | Description |
-| ----------- | ---- | ---------------- | ----------------------------------------------------- |
-| Major | 🌟 | `release:major` | Breaking changes that affect compatibility |
-| Feature | 🚀 | `release:minor` | New features or enhancements |
-| Patch | 🩹 | `release:patch` | Small fixes or improvements |
-| Fix | 🪲 | `release:patch` | Bugfixes (patch-level release impact) |
-| Docs | 📖 | `release:skip` | Documentation changes only |
-| Maintenance | ⚙️ | `release:skip` | Internal upkeep with no change to shipped behavior or integration contracts |
+- an icon or type prefix;
+- a Conventional Commit prefix such as `feat:` or `docs:`;
+- an issue reference;
+- a list of unrelated changes;
+- AI or agent attribution;
+- an implementation detail when a reader-facing result is available.
-`release:pre-release` is a release mode, not a change type. It uses one explicit
-bump label or the repository's configured `DefaultBump` when an open pull request
-must publish a prerelease. The mode alone supplies no level. Never combine it
-with `release:skip`; [Release Management](../Capabilities/release-management/design.md#version-computation)
-owns resolution and validation.
+## Write the description
-### Detecting the change type
+The description stands on its own for a reader who has not inspected the diff.
+Use the following structure.
-Decide the type from the change **for the declared target audience**, including its integrators, not from the maintainer's implementation effort or the names of changed files. Read the [audience declaration in the README](Readme-Driven-Context.md#target-audience) and any explicitly adopted initiative definition first. Resolve and record missing or ambiguous audience context before finalizing the type; do not guess it from repository ownership.
+### Summarize the result
-Assess every affected supported use: commands, parameters, APIs, output shapes, configuration, permissions, installation, and runtime/tool requirements. User and integrator may be the same person, as the [PSModule audience](../Initiatives/PSModule.md#target-audience) illustrates. An interactive command still working does not make a change compatible if the same user's supported script integration breaks.
+Start with one or two short paragraphs and no `Summary` heading. Lead with
+required action and breaking impact when either exists. A short unordered list
+is acceptable only when the change has several distinct result groups that
+cannot be stated clearly in prose.
-The change type is decided in this order:
+Use the vocabulary of the supported interface. Describe what changes, who is
+affected, and what they need to do. Keep implementation narration out of the
+summary.
-1. **Explicit user input** — if the contributor / Shipper specified a type, verify it against the audience impact and applicable version policy. Resolve a conflict before finalizing the release decision; a label does not make a breaking change compatible.
-2. **Pre-1.0.0 rule** — projects with no version tags or latest tag below `v1.0.0` follow [SemVer §4](https://semver.org/#spec-item-4). Major is **never** auto-detected for pre-1.0.0 projects. Breaking changes there are classified as Minor (`0.x.0`).
-3. **Find the affected consumer contracts** in the branch diff. Paths help locate evidence; they do not determine impact:
+### End the shareable summary
- | Artifact type | Recognition hints | Consumer contract to inspect |
- | --- | --- | --- |
- | Library / Module | Source and package manifest | Public commands/APIs, parameters, output shapes, defaults, installation, and supported runtimes. |
- | GitHub Action | `action.yml` and its implementation | Inputs, outputs, permissions, execution environment, and behavior. |
- | Reusable Workflow | Callable workflows under `.github/workflows/` | Caller inputs, secrets, permissions, configuration, tool requirements, and behavior. |
- | Infrastructure module | Module source, variables, and outputs | Variable/output contracts, defaults, provider requirements, and managed-resource behavior. |
+End the summary with the exact HTML marker shown in the
+[complete template](#copy-the-complete-template).
-4. **Classification rules** (apply in order, against those contracts):
- 1. **Docs** — documentation-only changes, not a functional change merely stored in a documentation file.
- 2. **Maintenance** — internal-only changes with no effect on shipped behavior or supported integration contracts.
- 3. **Major** — a supported user or integration contract breaks (pre-1.0.0 auto-detection maps this to Minor).
- 4. **Feature (Minor)** — backward-compatible capabilities are added.
- 5. **Patch or Fix** — backward-compatible fixes or small improvements.
+The marker appears exactly once, on its own line, outside a code fence, and
+before the first detailed section. Text before it must remain useful when shared
+without the rest of the description.
-Use the highest impact across the affected supported contracts, then apply the version policy. A small fix can be breaking; unrelated internal changes or documentation do not lower that impact.
+### Explain each reader-facing result
-A configured default supplies a release level, not evidence of compatibility. Check it against the audience impact and apply an explicit override when the change requires a different level.
+Use these classifiers in this order and omit empty groups:
-Illustrative cases, not release history:
+1. `## Breaking: `
+2. `## Removed: `
+3. `## New: `
+4. `## Changed: `
+5. `## Fixed: `
-| Change | Audience-based classification |
+| Classifier | Use when |
| --- | --- |
-| Remove a supported `Process-PSModule` caller input | Breaking for module maintainers integrating the workflow, not Maintenance because the edit is under `.github/`. |
-| Change a module's supported output shape or raise its minimum PowerShell version | Breaking for PowerShell users and their integrations, even if only a manifest or one line changes. |
-| Add an optional module parameter without changing existing calls | Feature (Minor): a compatible capability for the same PowerShell audience. |
+| `Breaking` | A supported consumer must act or an existing supported use becomes incompatible. |
+| `Removed` | A supported capability, interface, or documented path is no longer available. |
+| `New` | Readers gain a capability, interface, or body of guidance. |
+| `Changed` | Existing behavior, configuration, or guidance changes compatibly. |
+| `Fixed` | An incorrect behavior or guidance now works as intended. |
+
+Each section heading states one result, not a component name. Open the section
+with one or two prose paragraphs that explain what changes, why, affected
+supported uses, compatibility, and exact adoption actions or an explicit
+no-action result. Include applicable prerequisites, verification, and ordering
+constraints. A later release that supersedes an earlier action explains how
+consumers compose the remaining actions through its target; preserve any
+required intermediate installation or run. A documentation change uses the
+classifier that describes what its guidance now provides.
+
+### Show interfaces after the prose
+
+After the opening prose, add an interface example or compact table only when it
+makes the reader's action clearer. Do not lead a section with a code block or
+table. Include necessary old-to-new examples, before-and-after comparisons, or
+diagrams in the note itself when they explain an applicable transition. Keep
+release-specific migration details here; evergreen resource docs show supported
+usage without accumulating those transitions.
+
+Link optional usage documentation using an absolute default-branch URL or the
+canonical published URL so the link survives when the pull request becomes a
+release record. Such links supplement the note; consumers must not need them to
+discover required upgrade actions. Never include secret values.
+
+### Close each section with supporting details
+
+A named section may end with either or both of these optional blocks, in this
+order:
-## Description structure
+```markdown
+
+Technical details
-Ordered, top to bottom.
+Implementation and validation evidence for this result.
-### 1. Leading paragraph — Summary
+
-A concise paragraph describing **what changes for the user**. Present tense, active voice. Never open with implementation language ("Refactored", "Updated class", "Added null checks").
+
+Related references
-### 2. User-facing changes — sections with headers
+- Resolves MSXOrg/repository#123
+- Depends on MSXOrg/other-repository#456
-Organize by **what the user experiences**, not by what was changed internally.
+
+```
-- `## Breaking Changes` — what stopped working or changed incompatibly, regardless of the selected change type. Include pre-1.0 breaking behavior even when the version policy classifies it as Minor.
-- `## New: ` — new things the user can do.
-- `## Changed: ` — existing behavior that now works differently.
-- `## Fixed: ` — problems now resolved.
+The blocks are section-scoped. Do not add global catch-all `Technical details`
+or `Related references` blocks after several classified sections. If the pull
+request is internal-only and has no classified section, place its supporting
+blocks directly after the summary marker.
+
+Put the standards and framework alignment evidence required by
+[Implement](Workflow-Stages/Implement.md#5-standards-and-framework-alignment-pass)
+in the `Technical details` block for the result it supports. For a
+release-managed result, include the applicable consumer, template, and baseline
+evidence required by [Release
+Management](../Capabilities/release-management/spec.md#release-evidence) in that
+same scoped block. Keep the consumer's instructions in the result's prose and
+examples; the supporting evidence verifies those instructions rather than
+replacing them.
+
+Record the closing delivery leaf's implementation-plan progress and the
+[issue convergence sweep](Workflow-Stages/Implement.md#6-issue-convergence-sweep)
+search scope and outcome in that same block, including when no additional issue
+converges. For internal-only work without classified sections, the block after
+the summary marker carries this evidence and any applicable release evidence.
+
+Use fully qualified `owner/repository#number` references for every same-instance
+GitHub issue or pull request, including references to the current repository.
+Use closing keywords only for issues the complete change actually resolves.
+Prefix non-closing relationships with terms such as `References`, `Depends on`,
+or `Followed by`. Use absolute Markdown links for Jira, cross-instance GitHub,
+and references that will render outside GitHub.
+
+Do not include AI or agent attribution anywhere in the description.
+
+### Record release decisions only when invoked
+
+When the target route invokes Release Management, add one `Release decisions`
+block after the classified sections and apply the exact labels the block
+reports:
-Under each header:
+```markdown
+
+Release decisions
-- What the user can now do, or what changed for them.
-- Who is affected, including changed public parameters and defaults.
-- A link to the release-wide adoption path rather than a second sequence of instructions.
-- Examples or code snippets showing new usage.
+- **Release:** Yes - the delivered artifact and supported caller contract change.
+- **Version bump:** Minor - callers gain a compatible optional input.
+- **Mode:** Stable - the target route publishes stable releases.
+- **Labels:** `release:minor`
-Do **not** include private implementation details or refactoring decisions here. Exact public interface names belong here when users need them to understand or adopt the change.
+
+```
-### 3. Adopting this release
+For a no-release decision, include only the decision and its label:
-Every PR includes `## Adopting this release` before the technical details. Give one ordered, release-wide path for the affected consumers, with applicability, prerequisites, and any required intermediate steps. Adapt the actions to the artifact: a library call, workflow input, service setting, or infrastructure module may need different consumer changes.
+```markdown
+
+Release decisions
-When updating the reference is sufficient, state: **No configuration, code, or invocation changes are required beyond selecting this release.** For a non-releasing change, state its adoption outcome explicitly too. An empty section or an absent migration paragraph is not evidence that no action is needed.
+- **Release:** No - the change does not affect the artifact or its supported consumer contracts.
+- **Labels:** `release:skip`
-### 4. Release impact
+
+```
-Every PR includes `## Release impact`. Report the release resolver's decision; do not introduce a second version-selection policy.
+The evidence after each decision must identify the applicable route,
+configuration, and audience impact. List the exact resulting labels, or `None`
+when effective configuration supplies the release decision and no override
+label applies. Do not predict the final version; Release Management resolves it
+from the actual base.
+
+When the target route does not invoke Release Management, omit this block and
+all `release:*` labels. Do not add `release:skip` merely because the repository
+has no `.github/release.config.yml`.
+
+### Assemble the body
+
+Use this order:
+
+1. Summary prose.
+2. The shareable-summary marker.
+3. Classified sections in the required order, each with its own optional
+ `Technical details` and `Related references` blocks.
+4. Supporting blocks directly after the marker only when internal-only work has
+ no classified section.
+5. The conditional `Release decisions` block, only when the target route
+ invokes Release Management.
+
+Do not add a `Summary` heading, empty classified sections, global supporting
+blocks, or parallel release-note metadata.
+
+### Copy the complete template
+
+Start from this complete body. Replace every placeholder and delete every
+classifier section, supporting block, example, or release field that does not
+apply. Repeat a complete classifier section when several distinct results share
+the same classifier, and keep every remaining classifier group in the order
+shown.
+
+For internal-only work with no classified result, delete all five classifier
+groups and place one applicable `Technical details` block and `Related
+references` block directly after the marker. Delete the complete `Release
+decisions` block when the target route does not invoke Release Management. On an
+invoked route with a no-release decision, replace the release block with the
+shorter no-release form shown in
+[Record release decisions only when invoked](#record-release-decisions-only-when-invoked).
+
+For a publishing decision, retain the resolved bump and mode with their input
+sources. A valid effective `DefaultBump` needs no per-PR bump label: report
+`Labels: None` when no owned override applies, or the exact mode label when it
+does. Include configured release-candidate routing in the mode evidence. Never
+turn invalid settings or conflicting owned labels into a no-action result.
-When `DefaultBump` supplies an MSX release level, record the setting and value as the source. Unless a valid `release:skip` is selected, missing both an explicit level and a configured default fails the [required decision check](../Capabilities/release-management/design.md#required-pre-merge-decision-check) and blocks merge; never infer a patch release from missing input.
+````markdown
+{{ One or two short summary paragraphs that state what changes, why, who is
+affected, and required adoption actions or an explicit no-action result. }}
-| Field | Required content |
-| --- | --- |
-| Effective decision | The selected owned label and its semantic effect, or the configured policy that supplies the decision where supported. Identify the decision's source; do not assume a label name across producers. |
-| Semantic effect | Major, minor, patch, or no release, plus stable/prerelease mode where applicable. Describe breaking behavior separately from its version classification. |
-| Release/base coordinates | Before publication, state that final coordinates are resolved by the release process. The published record supplies the actual target version, tag, immutable source, version-computation base, and release/source baseline for the consumer delta, distinguishing the two bases when they differ. |
+
-Before publication, name the intended semantic effect and state that final coordinates are **resolved by the release process**. Do not assign a final version in advance or retain a numeric prediction after the base changes. The publisher records the actual coordinates in a distinct publication envelope without rewriting the authored body. For a first release, identify the initial versioning baseline and state that there is no prior release; for `release:skip`, state that no version is produced.
+## Breaking: {{ Reader-facing result }}
-### 5. Required ending blocks
+{{ Explain what changes, why, affected supported uses, compatibility, and exact
+adoption actions or an explicit no-action result. Include applicable
+prerequisites, verification, ordering, and any required intermediate installation
+or run. }}
-At the very end of every PR description, use this exact structure:
+{{ Interface or old-to-new example, comparison, or diagram after the prose when
+needed to make adoption unambiguous. Keep required transition details in this
+note; link to evergreen usage docs only for optional depth. Delete when prose
+is sufficient. }}
-```markdown
----
Technical details
-### Consumer change record
+{{ Implementation and validation evidence, closing delivery-leaf plan progress,
+and issue-convergence search scope and outcome for this result, even when no
+additional issue converges. }}
-
-
-### Template baseline
-
-
-
-### Maintainer evidence
+| Changed surface | Standards checked | Framework docs checked | Result |
+| --- | --- | --- | --- |
+| `{{ Path or interface }}` | {{ Applicable standards }} | {{ Applicable framework docs, or `None (no framework-specific docs)` }} | {{ `Aligned`, `Fixed in this PR`, or `Exception - MSXOrg/repository#123` }} |
-
+{{ For an applicable release-managed result, identify the consumer-change release
+and source baseline and evidence supporting the actions or no-action result
+above. For an affected integration template, identify its repository, verified
+compatible immutable commit, and compatibility evidence. Publication resolves
+actual release coordinates; do not predict a final version. Delete inapplicable
+evidence. }}
-Relevant issues (or links)
+Related references
-- Resolves Org/Repo#123
-- Resolves Org/OtherRepo#124
+- Resolves MSXOrg/repository#123
+- References MSXOrg/repository#456
+- Depends on MSXOrg/other-repository#789
-### Related work
+
-- Depends on Org/OtherRepo#124
-- Followed by Org/OtherRepo#125
-- References Org/OtherRepo#126
+## Removed: {{ Reader-facing result }}
-
-```
+{{ Explain what changes, why, affected supported uses, compatibility, and exact
+adoption actions or an explicit no-action result. Include applicable
+prerequisites, verification, ordering, and any required intermediate installation
+or run. }}
+
+{{ Interface or old-to-new example, comparison, or diagram after the prose when
+needed to make adoption unambiguous. Keep required transition details in this
+note; link to evergreen usage docs only for optional depth. Delete when prose
+is sufficient. }}
-The **Technical details** block uses the three `###` headings shown above to separate consumer evidence from maintainer evidence. The deeper headings below organize this standard, not the PR body.
+
+Technical details
-#### Consumer change record
+{{ Implementation and validation evidence, closing delivery-leaf plan progress,
+and issue-convergence search scope and outcome for this result, even when no
+additional issue converges. }}
-Use one row per affected surface. A stable identifier within the record lets the adoption steps and later release records refer to the same change.
+| Changed surface | Standards checked | Framework docs checked | Result |
+| --- | --- | --- | --- |
+| `{{ Path or interface }}` | {{ Applicable standards }} | {{ Applicable framework docs, or `None (no framework-specific docs)` }} | {{ `Aligned`, `Fixed in this PR`, or `Exception - MSXOrg/repository#123` }} |
-| Identifier / surface | Before | After | Applicability / prerequisites | Consumer action | Verification |
-| --- | --- | --- | --- | --- | --- |
-| `` | `` | `` | `` | `` | `` |
+{{ For an applicable release-managed result, identify the consumer-change release
+and source baseline and evidence supporting the actions or no-action result
+above. For an affected integration template, identify its repository, verified
+compatible immutable commit, and compatibility evidence. Publication resolves
+actual release coordinates; do not predict a final version. Delete inapplicable
+evidence. }}
-Record exact changed configuration keys, workflow contracts, permissions, secret **names, never values**, public APIs, runtime/tool requirements, defaults, removals, and behavior. A list of changed filenames alone is insufficient. Link to numbered detail in the adoption path when commands or coordinated edits need more room; do not maintain competing instructions.
+
-Record no-action outcomes explicitly, including changes that affect behavior but require no consumer edit. If no consumer-facing surface changes, say so instead of leaving an empty table. Applicability distinguishes consumers that need an action from those already using the released contract.
+
+Related references
-#### Template baseline
+- Resolves MSXOrg/repository#123
+- References MSXOrg/repository#456
+- Depends on MSXOrg/other-repository#789
-Where a framework or product has an applicable integration template, record:
+
-| Field | Required content |
-| --- | --- |
-| Producer identity | Producer version and immutable source, or the immutable candidate source before publication. |
-| Template identity | Template repository and full immutable commit SHA, not a branch, floating tag, or today's latest template. |
-| Compatibility evidence | Evidence that this template commit works with the identified producer source, including required integration surfaces and the relevant validation result. |
-| Template work | Linked template PRs and their delivery state, or a justified no-change result. An earlier compatible commit may be reused when the evidence supports it. |
+## New: {{ Reader-facing result }}
-Every applicable release identifies its verified compatible baseline; a claim of compatibility without evidence is insufficient. If no template applies, state that fact and why. Do not invent a template or describe pending template work as delivered.
+{{ Explain what changes, why, affected supported uses, compatibility, and exact
+adoption actions or an explicit no-action result. Include applicable
+prerequisites, verification, ordering, and any required intermediate installation
+or run. }}
-#### Maintainer evidence
+{{ Interface or old-to-new example, comparison, or diagram after the prose when
+needed to make adoption unambiguous. Keep required transition details in this
+note; link to evergreen usage docs only for optional depth. Delete when prose
+is sufficient. }}
-Keep internal implementation notes separate from the consumer record:
+
+Technical details
-- Which internal functions, classes, or files were changed.
-- Implementation approach and design decisions.
-- Internal compatibility considerations not already owned by the consumer record.
-- **Implementation plan progress** — cross-reference the closing Task or Bug's plan. Which plan steps does this PR complete? Which were moved to follow-up delivery issues?
-- **Standards and framework alignment** — the result of the [alignment pass](Workflow-Stages/Implement.md#5-standards-and-framework-alignment-pass), as one row per changed surface. The stage procedure owns when and how the pass is run; this block only carries its evidence.
-- **Issue convergence sweep** — the scope used for the [session-end sweep](Workflow-Stages/Implement.md#6-issue-convergence-sweep) and which additional open issues (if any) the finished diff fully satisfied.
+{{ Implementation and validation evidence, closing delivery-leaf plan progress,
+and issue-convergence search scope and outcome for this result, even when no
+additional issue converges. }}
| Changed surface | Standards checked | Framework docs checked | Result |
| --- | --- | --- | --- |
-| `src/**` (PowerShell) | Naming, Functions | Module source layout | Aligned |
-| `.github/workflows/**` | GitHub Actions | Reusable workflow contract | Exception — Org/Repo#123 |
+| `{{ Path or interface }}` | {{ Applicable standards }} | {{ Applicable framework docs, or `None (no framework-specific docs)` }} | {{ `Aligned`, `Fixed in this PR`, or `Exception - MSXOrg/repository#123` }} |
-A result is `Aligned`, `Fixed in this PR`, or `Exception` with a link to the follow-up issue that carries it. A surface with no framework or domain documentation of its own is recorded as `None (no framework-specific docs)`.
+{{ For an applicable release-managed result, identify the consumer-change release
+and source baseline and evidence supporting the actions or no-action result
+above. For an affected integration template, identify its repository, verified
+compatible immutable commit, and compatibility evidence. Publication resolves
+actual release coordinates; do not predict a final version. Delete inapplicable
+evidence. }}
-The **Relevant issues (or links)** block is required and uses fully qualified references (`Org/Repo#N`) so links work across repositories.
-
-Use one bullet per linked reference. Begin with the closing issues, each prefixed with `Resolves`; this applies to the scoped Task or Bug delivered by the pull request and to additional issues the [issue convergence sweep](Workflow-Stages/Implement.md#6-issue-convergence-sweep) confirms are fully satisfied by the same finished diff. When the PR relates to other issues or pull requests, add a `### Related work` header below the `Resolves` list, then list each qualified reference with its relationship, such as `Depends on`, `Followed by`, or `References`. Closing keywords do not close pull requests. A parent PBI or Epic may appear as context without a closing keyword; never close an aggregate through a delivery pull request. Partially convergent or supporting issues are linked as non-closing context.
+
-A PR that delivers a scoped Task or Bug must include at least one `Resolves` link. A PR that does not resolve an issue must include a `### Related work` header and an unordered list of qualified relationship references. If additional `Resolves` links are used, include sweep evidence in Technical details that shows those issues are fully satisfied. The [Issue Hierarchy](Issues/Types/Hierarchy.md) and [Issue Lifecycle](Issues/Process/Lifecycle.md) own type and closure semantics.
+
+Related references
-## Formatting
+- Resolves MSXOrg/repository#123
+- References MSXOrg/repository#456
+- Depends on MSXOrg/other-repository#789
-- Paragraphs are written as a **single unbroken line**. GitHub renders mid-paragraph newlines as spaces.
-- The PR description is **the release note**. Write it for users, not reviewers.
-- The PR title and description align with the closing Task or Bug's user-facing framing and recorded technical decisions.
-- Refer to every issue or pull request as `Org/Repo#N`, including references in the current repository; do not use bare `#N` references.
+
-## Example
+## Changed: {{ Reader-facing result }}
-This illustrative configuration change uses the same record shape for any artifact type; it does not depend on a particular package manager, language, or deployment mechanism.
+{{ Explain what changes, why, affected supported uses, compatibility, and exact
+adoption actions or an explicit no-action result. Include applicable
+prerequisites, verification, ordering, and any required intermediate installation
+or run. }}
-````markdown
-Job timeouts use the explicit `timeoutSeconds` setting. Existing timeout values and the 30-second default are unchanged.
+{{ Interface or old-to-new example, comparison, or diagram after the prose when
+needed to make adoption unambiguous. Keep required transition details in this
+note; link to evergreen usage docs only for optional depth. Delete when prose
+is sufficient. }}
-## Breaking Changes
-
-The `timeout` configuration key is removed. Configurations that still supply it are rejected. Rename it using the [adoption path](#adopting-this-release); configurations that omit the key need no configuration edit.
+
+Technical details
-## Adopting this release
+{{ Implementation and validation evidence, closing delivery-leaf plan progress,
+and issue-convergence search scope and outcome for this result, even when no
+additional issue converges. }}
-1. If the job configuration sets `timeout`, rename that key to `timeoutSeconds`, preserving its positive integer value in seconds. For example, `timeout: 20` becomes `timeoutSeconds: 20`. Do not supply both keys. If the key is absent, retain the 30-second default without adding a setting.
-2. Select the published release through the integration's version reference or deployment mechanism. Apply the configuration edit with that version change, not to the previous version.
-3. Run the existing configuration validation against the selected version: `timeoutSeconds: 20` is accepted and the removed `timeout: 20` is rejected. Run the existing timeout check to confirm cancellation at the configured limit, or 30 seconds when omitted.
+| Changed surface | Standards checked | Framework docs checked | Result |
+| --- | --- | --- | --- |
+| `{{ Path or interface }}` | {{ Applicable standards }} | {{ Applicable framework docs, or `None (no framework-specific docs)` }} | {{ `Aligned`, `Fixed in this PR`, or `Exception - MSXOrg/repository#123` }} |
-## Release impact
+{{ For an applicable release-managed result, identify the consumer-change release
+and source baseline and evidence supporting the actions or no-action result
+above. For an affected integration template, identify its repository, verified
+compatible immutable commit, and compatibility evidence. Publication resolves
+actual release coordinates; do not predict a final version. Delete inapplicable
+evidence. }}
-| Field | Value |
-| --- | --- |
-| Effective decision | `release:major`, selected for removal of a supported configuration key. |
-| Semantic effect | Major, stable; existing explicit configurations require the edit above. |
-| Release/base coordinates | The release process resolves the actual version base, change baseline, target version, tag, and immutable source at publication. No final numeric version is assigned in this PR. |
+
----
-Technical details
+Related references
-### Consumer change record
+- Resolves MSXOrg/repository#123
+- References MSXOrg/repository#456
+- Depends on MSXOrg/other-repository#789
-| Identifier / surface | Before | After | Applicability / prerequisites | Consumer action | Verification |
-| --- | --- | --- | --- | --- | --- |
-| TIMEOUT-KEY / job configuration | Optional `timeout`, a positive integer in seconds; default 30. | Optional `timeoutSeconds`, with the same units and default; `timeout` is rejected. | Every integration; only configurations using the removed key need an edit. | Rename the key without changing its value; see adoption steps 1-2. No configuration change when omitted. | Adoption step 3 accepts the new key, rejects the old key, and confirms the timeout behavior. |
+
+
+## Fixed: {{ Reader-facing result }}
-### Template baseline
+{{ Explain what changes, why, affected supported uses, compatibility, and exact
+adoption actions or an explicit no-action result. Include applicable
+prerequisites, verification, ordering, and any required intermediate installation
+or run. }}
-Not applicable: this product does not distribute an integration template.
+{{ Interface or old-to-new example, comparison, or diagram after the prose when
+needed to make adoption unambiguous. Keep required transition details in this
+note; link to evergreen usage docs only for optional depth. Delete when prose
+is sufficient. }}
-### Maintainer evidence
+
+Technical details
-- The configuration parser accepts `timeoutSeconds` and reports the removed key as invalid.
-- Implementation plan progress: all steps in Org/Repo#218 are complete, including explicit-value and default-value coverage.
-- Issue convergence sweep: configuration and timeout issues were inspected; no additional issue is fully satisfied.
+{{ Implementation and validation evidence, closing delivery-leaf plan progress,
+and issue-convergence search scope and outcome for this result, even when no
+additional issue converges. }}
| Changed surface | Standards checked | Framework docs checked | Result |
| --- | --- | --- | --- |
-| Configuration parsing and timeout behavior | Naming, Error Handling, Testing | Product configuration contract | Aligned |
+| `{{ Path or interface }}` | {{ Applicable standards }} | {{ Applicable framework docs, or `None (no framework-specific docs)` }} | {{ `Aligned`, `Fixed in this PR`, or `Exception - MSXOrg/repository#123` }} |
+
+{{ For an applicable release-managed result, identify the consumer-change release
+and source baseline and evidence supporting the actions or no-action result
+above. For an affected integration template, identify its repository, verified
+compatible immutable commit, and compatibility evidence. Publication resolves
+actual release coordinates; do not predict a final version. Delete inapplicable
+evidence. }}
-Relevant issues (or links)
+Related references
-- Resolves Org/Repo#218
+- Resolves MSXOrg/repository#123
+- References MSXOrg/repository#456
+- Depends on MSXOrg/other-repository#789
-### Related work
+
-- References Org/Repo#220
+
+Release decisions
+
+- **Release:** {{ Yes or No }} - {{ Evidence from the artifact, route, and
+ supported consumer contract. }}
+- **Version bump:** {{ Patch, Minor, or Major }} - {{ Compatibility evidence.
+ Identify the explicit label, supported caller input, repository setting, or
+ documented shared default that supplies it. Delete this field when Release
+ is No. }}
+- **Mode:** {{ Stable or Prerelease }} - {{ Target-route or override evidence.
+ Identify configured release-candidate routing when applicable. Delete this
+ field when Release is No. }}
+- **Labels:** {{ Exact `release:*` labels, or `None` when effective configuration
+ supplies the decision without an override label. }}
````
-For a no-action patch, keep both required user-facing blocks. State the no-action adoption outcome and record either the affected behavior with `No consumer edit required` or `No consumer-facing surface changes` under Consumer change record. Do not copy the breaking example's configuration actions into an unaffected release.
-
-## Drafts and readiness
-
-- The Shipper always creates the PR as **draft** so CI attaches immediately.
-- A pull request is marked ready only when it meets every item in the [Definition of Ready for Review](Definition-of-Ready-and-Done.md#definition-of-ready-for-review) — nothing in that gate is left open. That page is the single checklist; this section does not restate it.
-- Marking ready is a gate, not a person: anyone who can verify that gate — a contributor, or an agent acting on their behalf — may mark it ready. The gate, not the actor, is what makes it ready.
-- Once ready, enable auto-merge (squash) so the change lands when review approves and the required checks stay green. See [Branching and Merging](Branching-and-Merging.md#required-checks-and-auto-merge).
-
-## Branches and commits
-
-- Branch naming: `/-`, e.g. `fix/123-pagination-truncation`.
-- Commit messages: plain, direct, descriptive. **No conventional-commit prefixes** (`fix:`, `feat:`, `docs:`). See [Commit Conventions](Commit-Conventions.md).
-- Self-review the staged diff before each commit. Unintended files (debug output, editor temp, credentials) get caught before they reach the remote.
-
-## Labels and assignment
-
-- Apply an owned release label for an explicit decision or override. A matching configured `DefaultBump` may supply the bump without a label; record that source. Use `release:skip` for an explicit no-release decision.
-- Apply phase labels if the repo uses them (Planning, Implementation, etc.).
-- Assign the current user.
-- Request reviewers per `CODEOWNERS`; if none, fall back to repo defaults or skip.
+## Check readiness
+
+Before marking the pull request ready, verify:
+
+- the title states one result and contains none of the prohibited prefixes,
+ references, lists, or attribution;
+- the summary is accurate on its own and the marker appears exactly once in the
+ required position;
+- every claim matches the complete diff or promotion range;
+- the complete delivered range since the identified consumer-change baseline is
+ covered, including every bundled consumer delta;
+- classified sections are non-empty, ordered, and grouped by reader-facing
+ result;
+- the notes explain what changed, why, affected supported uses, compatibility,
+ and exact applicable actions or an explicit no-action result, without
+ requiring PRs, diffs, or historical product docs to discover instructions;
+- release-order composition preserves required intermediate operations without
+ assuming every intermediate version must be installed;
+- prose precedes optional examples and tables;
+- supporting blocks are scoped to their section and ordered correctly;
+- same-instance references are fully qualified and closing keywords are
+ accurate;
+- release metadata and `release:*` labels are absent when the route does not
+ invoke Release Management;
+- when Release Management applies, the decision block, labels, effective
+ configuration, and complete-change evidence agree;
+- the description contains no AI or agent attribution.
+
+The pull request still follows the complete [Definition of Ready for
+Review](Definition-of-Ready-and-Done.md#definition-of-ready-for-review).
+
+## Where this connects
+
+- [README-Driven Context](Readme-Driven-Context.md) — where the product audience
+ and supported interfaces are declared.
+- [Contribution Workflow](Contribution-Workflow.md) — how a draft pull request
+ moves through automated and human review.
+- [Definition of Ready and Done](Definition-of-Ready-and-Done.md) — the gate
+ before review and completion.
+- [Branching and Merging](Branching-and-Merging.md) — branch, integration, and
+ merge rules.
+- [Automation Labels](Automation-Labels.md) — ownership and meaning of
+ `release:*` labels.
+- [Release Management](../Capabilities/release-management/design.md) — release
+ invocation, configuration, decision resolution, and publication.
diff --git a/src/docs/Ways-of-Working/Readme-Driven-Context.md b/src/docs/Ways-of-Working/Readme-Driven-Context.md
index d495da8..bd15d67 100644
--- a/src/docs/Ways-of-Working/Readme-Driven-Context.md
+++ b/src/docs/Ways-of-Working/Readme-Driven-Context.md
@@ -38,7 +38,7 @@ Every repository README MUST identify its target audience, the jobs the product
**User and integrator are roles, not necessarily different people.** An integration interface is user-facing when the audience depends on it; it does not become internal because its users write scripts, compose APIs, or maintain another product. The audience is not inferred from who authors or reviews a pull request.
-Detailed users and jobs belong in the [capability specification](Spec-Driven-Development.md#what-a-specification-is), linked from the README rather than copied. This declared audience anchors [change classification](PR-Format.md#detecting-the-change-type) and the consumer evidence in release notes.
+Detailed users and jobs belong in the [capability specification](Spec-Driven-Development.md#what-a-specification-is), linked from the README rather than copied. This declared audience anchors [reader identification](PR-Format.md#identify-the-readers) and the evidence in pull request descriptions.
## When to update the README
diff --git a/src/docs/Ways-of-Working/Repository-Standard.md b/src/docs/Ways-of-Working/Repository-Standard.md
index 1bbc6b9..013f710 100644
--- a/src/docs/Ways-of-Working/Repository-Standard.md
+++ b/src/docs/Ways-of-Working/Repository-Standard.md
@@ -166,20 +166,23 @@ When a tool only discovers config at the repository root, keep it there and docu
## Pull request defaults
-Repository pull requests must use the PR Manager style for title and description when a release note may be generated from the PR.
-
-Default title pattern:
-
-```text
- []:
-```
-
-Use [PR Format](PR-Format.md) for audience-based change classification and the complete description structure, including its required consumer evidence and ending blocks. A PR closes one scoped Task or Bug, with any additional closing links limited to issues the session-end convergence sweep shows are fully delivered by the same diff.
+Repository pull requests follow [PR Format](PR-Format.md): one short
+reader-facing result in the title, an audience-first description of the complete
+change, and supporting evidence scoped to the result it supports. Repository or
+initiative guidance MUST NOT add an icon, type prefix, issue reference, or
+internal campaign identifier to the title.
+
+A pull request closes one scoped Task or Bug, with any additional closing links
+limited to issues the session-end convergence sweep shows are fully delivered by
+the same diff. When the target route invokes Release Management, the description
+and labels carry its evidence-based release decision. A route without that
+invocation carries neither the `Release decisions` block nor `release:*` labels.
The organization-level `.github` repository supplies the default template.
The repository-local contribution guide directs humans and agents to the
-organization template and its required format. A repository carries a local
-template only for a documented exception.
+organization template and the canonical format. The inherited template is a
+scaffold; PR Format remains authoritative. A repository carries a local template
+only for a documented exception.
## Managed files
@@ -218,7 +221,7 @@ For example, PSModule can define its module-specific managed files in `PSModule/
- [Agentic Development](../Capabilities/agentic-development/index.md) — which agent files a repository carries and why the entry point is a pointer.
- [Repository Type Property](Repository-Type-Property.md) — the `Type` custom property that classifies a repository and drives which type-specific files and controls apply.
- [README-Driven Context](Readme-Driven-Context.md) — why the README is the front door.
-- [PR Format](PR-Format.md) — the PR Manager-style title and description format.
+- [PR Format](PR-Format.md) — the audience-first title and description format.
- [Natural Language](../Coding-Standards/Natural-Language.md) — which language each artifact is written in, and how English prose is written.
- [GitHub Actions](../Coding-Standards/GitHub-Actions.md) — workflow and automation standards.
- [Dependency Updates](../Capabilities/dependency-updates/spec.md) — supply-chain update requirements.
diff --git a/src/docs/Ways-of-Working/Workflow-Stages/Implement.md b/src/docs/Ways-of-Working/Workflow-Stages/Implement.md
index 021b485..cb7ac6f 100644
--- a/src/docs/Ways-of-Working/Workflow-Stages/Implement.md
+++ b/src/docs/Ways-of-Working/Workflow-Stages/Implement.md
@@ -5,7 +5,7 @@ description: Procedure for the Workflow stage that delivers one ready Task or Bu
# Implement
-Implement is the delivery stage of the canonical [Workflow](../Workflow.md). It takes one ready, unblocked Task or Bug and produces working software in a review-ready pull request. The stage owns branching, coding, committing, opening the pull request, tracking progress, running the automated review loop, responding to feedback, and finalizing the release note. Implement builds delivery leaves; it does not implement an Epic or PBI aggregate, plan from scratch, or supply the independent review.
+Implement is the delivery stage of the canonical [Workflow](../Workflow.md). It takes one ready, unblocked Task or Bug and produces working software in a review-ready pull request. The stage owns branching, coding, committing, opening the pull request, tracking progress, running the automated review loop, responding to feedback, and finalizing the pull request description and any applicable release metadata. Implement builds delivery leaves; it does not implement an Epic or PBI aggregate, plan from scratch, or supply the independent review.
## Enter this stage when
@@ -64,7 +64,7 @@ Record the outcome as one row per changed surface:
| `src/functions/**` (PowerShell) | Naming, Functions, Error Handling | Module source layout | Aligned |
| `.github/workflows/**` | GitHub Actions | Reusable workflow contract | Exception — Owner/Repo#123 |
-A result is `Aligned`, `Fixed in this PR`, or `Exception` with a link that justifies it. Where a changed surface has no framework or domain documentation of its own, write `None (no framework-specific docs)` rather than inventing a pseudo-link. Carry the table into the pull request's Technical details block per [PR Format](../PR-Format.md), so [Review](Review.md) can verify the pass instead of guessing whether it happened.
+A result is `Aligned`, `Fixed in this PR`, or `Exception` with a link that justifies it. Where a changed surface has no framework or domain documentation of its own, write `None (no framework-specific docs)` rather than inventing a pseudo-link. Put each row in the `Technical details` block for the pull request section whose result it supports. For internal-only work without a classified section, put the table in the supporting block after the summary marker. This keeps the evidence scoped per [PR Format](../PR-Format.md) so [Review](Review.md) can verify the pass instead of guessing whether it happened.
**Stop rule.** Fix what is in scope for the closing Task or Bug and small enough to keep the pull request reviewable. When a finding is out of scope, systemic across the repository, or would change the shape of the pull request, file a follow-up issue through [Define](Define.md), link it in the table as an exception, and leave the change as it is. The pass improves alignment; it does not turn into a second delivery.
@@ -75,15 +75,15 @@ Run this once per implementation session, at the same timing as the standards/fr
1. Search for already-open issues whose asks are already satisfied by the finished diff, not only the issue originally linked when the branch was opened.
2. Scope the sweep deliberately so it scales: prioritize the delivery leaf's parent and siblings in the [Issue Hierarchy](../Issues/Types/Hierarchy.md), then narrow by affected component, labels, keywords, or code paths. Do not read every open issue serially in large repositories.
3. Treat convergence as outcome-based:
- - **Fully satisfied** — the diff already delivers the issue's ask. Add it to the pull request's Relevant issues block with `Resolves` so merge closes it.
- - **Partially satisfied** — the diff helps but does not fully deliver the ask. Link it as non-closing context and keep or create a follow-up delivery leaf for the remaining gap.
+ - **Fully satisfied** — the diff already delivers the issue's ask. Add it to the applicable section's `Related references` block with `Resolves` so merge closes it.
+ - **Partially satisfied** — the diff helps but does not fully deliver the ask. Add it to the applicable `Related references` block as non-closing context and keep or create a follow-up delivery leaf for the remaining gap.
4. Keep this pass focused on convergence and linkage. It does **not** rewrite, reformat, or otherwise "fix up" issue bodies to match issue templates; issue quality edits are separate work routed through [Define](Define.md).
### 7. Finalize and hand off
When the change meets the [Definition of Ready for Review](../Definition-of-Ready-and-Done.md):
-1. Finalize the title, release-note description, and effective release decision and its source per [PR Format](../PR-Format.md).
+1. Finalize the title and release-note-ready description per [PR Format](../PR-Format.md). When the target route invokes Release Management, also reconcile the `Release decisions` block and applied `release:*` labels with the effective configuration; otherwise omit them.
2. Mark the pull request ready and enable auto-merge per [Branching and Merging](../Branching-and-Merging.md).
## Operating rules
diff --git a/src/docs/Ways-of-Working/Workflow-Stages/Review.md b/src/docs/Ways-of-Working/Workflow-Stages/Review.md
index 0fd096d..1e28ee8 100644
--- a/src/docs/Ways-of-Working/Workflow-Stages/Review.md
+++ b/src/docs/Ways-of-Working/Workflow-Stages/Review.md
@@ -33,6 +33,10 @@ Check each dimension per [Review Etiquette](../Review-Etiquette.md):
- **Taste** — readability, naming, structure, tests that exercise behaviour.
- **Security** — input validation, no secrets in logs, external action and reusable-workflow references pinned to full commit SHAs, owned major-tag references meeting the controlled-release exception, and least privilege. Escalate a deep pass to [Security Review](Security-Review.md).
- **Documentation** — updated where user-facing behaviour changed.
+- **Pull request artifact** — the title states one result, the description follows
+ [PR Format](../PR-Format.md), supporting evidence is section-scoped, and
+ release metadata appears only when the target route invokes Release
+ Management.
- **Standards and framework alignment** — the pull request records the author's [alignment pass](Implement.md#5-standards-and-framework-alignment-pass), the result covers every changed surface, and each exception links a real follow-up issue. Spot-check at least one row against the canonical standard or framework page rather than trusting the summary; a missing or hollow pass is a blocking finding.
- **Issue convergence sweep** — the pull request records the author's [sweep](Implement.md#6-issue-convergence-sweep), including scoped search coverage and any convergent issues linked with closing keywords. Spot-check at least one linked closing issue against the delivered diff; a claimed convergence with no visible delivery evidence is a blocking finding.
- **Tests** — new behaviour has tests; bugs get regression tests.
@@ -58,6 +62,7 @@ An approval co-signs the change, so approve once the blocking concerns are resol
- [Review Etiquette](../Review-Etiquette.md) — tone, severity, and how to disagree well.
- [Implement](Implement.md#5-standards-and-framework-alignment-pass) and [Implement](Implement.md#6-issue-convergence-sweep) — the author-side session-end passes this stage verifies.
-- [PR Format](../PR-Format.md) — delivery-leaf closure and contextual aggregate links.
+- [PR Format](../PR-Format.md) — reader-facing titles and descriptions,
+ supporting references, and conditional release metadata.
- [Branching and Merging](../Branching-and-Merging.md) — who approves and how a change lands.
- [Security Review](Security-Review.md) — the specialized security path.
diff --git a/src/docs/Ways-of-Working/Workflow.md b/src/docs/Ways-of-Working/Workflow.md
index 58f1b0a..bad4672 100644
--- a/src/docs/Ways-of-Working/Workflow.md
+++ b/src/docs/Ways-of-Working/Workflow.md
@@ -136,7 +136,10 @@ See [Review Etiquette](Review-Etiquette.md).
Human review approves the ready pull request and the required checks stay green, so auto-merge lands the change — squash-merged into the protected branch, its branch deleted — and closes its Task or Bug. Where the project releases from the trunk, the merge cuts the release.
-The pull request description becomes the release note. Write it for end users, not reviewers.
+The pull request description is release-note-ready. When Release Management
+publishes it, the description becomes part of the release record; otherwise it
+remains the durable change record. Write it for the identified readers, not
+only for reviewers.
Parent PBI and Epic issues close separately when their native children and aggregate acceptance criteria are complete. See [PR Format](PR-Format.md), [Issue Lifecycle](Issues/Process/Lifecycle.md), and [Branching and Merging](Branching-and-Merging.md#required-checks-and-auto-merge).
diff --git a/src/docs/Ways-of-Working/index.md b/src/docs/Ways-of-Working/index.md
index 4ae7e6e..67d4386 100644
--- a/src/docs/Ways-of-Working/index.md
+++ b/src/docs/Ways-of-Working/index.md
@@ -35,7 +35,7 @@ This section documents the principles, processes, and norms that every contribut
| [Goal-Setting Framework](Goal-Setting.md) | Mission, OKRs, and Initiatives — the strategy above repository Epics. |
| [Definition of Ready and Done](Definition-of-Ready-and-Done.md) | The three gates that bracket every piece of work. |
| [Issues](Issues/index.md) | How issues are formatted and organized across the MSX ecosystem. |
-| [PR Format](PR-Format.md) | Pull request title, description, change types, and labels. |
+| [PR Format](PR-Format.md) | Audience-first pull request titles and descriptions with evidence-based, conditional release decisions. |
| [Commit Conventions](Commit-Conventions.md) | How commit messages are written. |
| [Branching and Merging](Branching-and-Merging.md) | Delivery-leaf topic branches, pull-request-only integration, and merge models. |
| [Review Etiquette](Review-Etiquette.md) | Tone, scope, severity, and how to disagree well. |