diff --git a/README.md b/README.md
index f3dab58..286949e 100644
--- a/README.md
+++ b/README.md
@@ -2,6 +2,8 @@
The top-of-tree documentation for everything **MSX** builds on GitHub — the vision, principles, ways of working, and coding standards that every organization, repository, and agent in the ecosystem inherits.
+Contributors, maintainers, integrators, and their agents use the published docs and plugin entry points to build and adopt MSX projects.
+
Published with [Zensical](https://zensical.org) to GitHub Pages: **[msxorg.github.io/docs](https://msxorg.github.io/docs/)**.
## What's inside
diff --git a/src/docs/Capabilities/release-management/design.md b/src/docs/Capabilities/release-management/design.md
index f02ce15..ff0a24f 100644
--- a/src/docs/Capabilities/release-management/design.md
+++ b/src/docs/Capabilities/release-management/design.md
@@ -1,14 +1,14 @@
---
title: Design
-description: How release management is built — a shared reusable workflow that reads pull-request labels, computes the SemVer bump, and cuts the release.
+description: How release management is built — a shared reusable workflow that resolves an explicit or configured SemVer bump, builds once, and publishes.
---
# 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`; everything else has a sensible default, so a
-minimal caller plus a one-line path filter is enough to adopt it.
+`.github/release.config.yml`. The workflow supplies the shared mechanics; an
+explicit label or an intentionally configured default supplies the release level.
## Branching model
@@ -19,8 +19,8 @@ A **release branch** is any branch configured as a release target, each with a
produces stable releases. Prereleases are opt-in via a PR label.
- **Multi-branch.** `dev` (prerelease) collects PRs and publishes a prerelease
on every merge; `main` (stable) receives `dev`. Merging `dev → main` computes
- the stable version from the **latest stable release** plus the merge PR's bump
- label — the prerelease counter does not carry over.
+ the stable version from the **latest stable release** plus the merge PR's
+ resolved bump — the prerelease counter does not carry over.
- **One production authority.** At most one branch is `release-type: stable`;
every other release branch is `prerelease`. The single stable branch
(typically `main`) owns the production version — a prerelease branch can never
@@ -71,22 +71,48 @@ Two consequences follow, and they are the point of the model:
## Version computation
-Release automation reads only labels in its `release:` namespace:
+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:
+
+```yaml
+# .github/release.config.yml
+DefaultBump: patch
+```
| Label | Meaning | Valid combination |
| --- | --- | --- |
-| `release:patch` | Resolve the next patch version. | Exactly one bump label. |
-| `release:minor` | Resolve the next minor version. | Exactly one bump label. |
-| `release:major` | Resolve the next major version. | Exactly one bump label. |
-| `release:pre-release` | Publish the open pull request as a prerelease. | With exactly one bump label. |
+| `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:skip` | Run validation without resolving or publishing a version. | Alone. |
-Exactly one bump label or `release:skip` is required; **no default** is applied.
-`release:pre-release` is an optional mode label, not a bump. A missing decision,
-multiple bump labels, `release:skip` with another release label, or
-`release:pre-release` without one bump label is **rejected**, so the outcome is
-always a decision someone made. Bare `major`, `minor`, and `patch` labels are
-ignored.
+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.
+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 |
+| --- | --- | --- |
+| `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. |
+| Multiple bump labels, or skip with another owned release label | Any | Fail: conflicting decisions; no fallback. |
+| Any | Invalid value | Fail: invalid configuration; no fallback. |
- **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);
@@ -94,15 +120,42 @@ ignored.
- The tag is created on the commit now at the head of the release branch —
squash, merge-commit, and rebase strategies alike.
+### 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.
+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.
+
+Configure the check's exact name as required in the protected branch's ruleset
+or branch protection, following [Merge Automation](../merge-automation/spec.md).
+Manual merge and auto-merge both wait for it: failure, pending execution, and
+absence block merge. A warning or an advisory, unrequired check is insufficient.
+Human review still assesses whether the resolved level matches the audience
+impact; CI validates the deterministic decision contract.
+
+The release run validates its actual inputs again before Resolve and Build.
+Pre-merge validation does not replace release-time validation, but a known
+missing decision is never deferred until after merge.
+
### Optional ad hoc releases
-The standard release path is a labeled pull request merged into a release
+The standard release path is a pull request with a validated decision merged into a release
branch. `workflow_dispatch` is an optional extension, not part of the minimum
implementation. An implementation SHOULD omit it unless its product has a real
need to release already-reviewed content outside the merge flow.
-Where an ad hoc path exists, it requires an explicit bump, source ref, release-note
-summary, and reason. It resolves the source ref to an immutable commit and enters
+Where an ad hoc path exists, it requires an explicit bump, source ref, complete
+release-note context meeting the [release evidence contract](#release-notes), and
+reason. It resolves the source ref to an immutable commit and enters
the same Resolve → Build → Test → Publish pipeline as a merged pull request. It
does not infer a bump, bypass validation, rebuild an existing version, or make a
direct push into a release interface.
@@ -117,9 +170,9 @@ 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` alongside exactly one bump label on an open PR publishes
- `v-.`: `base` is the next version from the PR's bump
- label, `identifier` is the normalized branch name, and `counter`
+- **PR-level** — `release:pre-release` with a resolved explicit or configured bump publishes
+ `v-.`: `base` is the next version from that bump,
+ `identifier` is the normalized branch name, and `counter`
auto-increments per push.
- Artifact-specific conventions replace the SemVer suffix where they exist
(`-alpha.N` for npm, `.devN` for Python). Release candidates use `-rc.N`,
@@ -134,21 +187,104 @@ 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.
+Derive these paths from the delivered product and its
+[audience-facing contracts](../../Ways-of-Working/PR-Format.md#detecting-the-change-type),
+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.
+
+This example represents a workflow producer with a public `reusable.yml` entry
+point and its local implementation; each producer lists its own artifact inputs.
+
```yaml
release-paths:
+ - ".github/workflows/reusable.yml" # public caller contract
+ - ".github/actions/**" # this workflow's local implementation
- "src/**"
- - "Dockerfile"
- - "action.yml"
- - "!docs/**" # documentation-only changes never release
- - "!.github/**" # CI/CD changes never release
```
## Release notes
-The GitHub Release **name** is the version. Its **body** is the pull request title
-and description for the standard merge path, or the required release-note summary
-for an optional ad hoc dispatch. The same note is handed to
-[Downstream Release Propagation](../downstream-release-propagation/design.md).
+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.
+
+### 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.
+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
+ same artifact. An authored statement that coordinates resolve at publication
+ is not replaced with a manual prediction.
+3. **Publish the complete record.** Preserve the captured title and body
+ unchanged, with a clearly separated publication envelope. Compare the
+ published authored portion with the snapshot; truncation, summarization,
+ missing evidence, or a source mismatch is a publication failure, not success.
+ Hand the same complete record to every note-bearing publishing target and
+ [Downstream Release Propagation](../downstream-release-propagation/design.md).
+
+The envelope records these resolved facts without becoming a second authored
+release note:
+
+| Field | Value |
+| --- | --- |
+| Release identity | Actual version, stable/prerelease mode, tag, immutable source commit, and artifact identity or digest where applicable. |
+| Effective decision | The resolved semantic effect and its owned-label or configured-policy source; [version computation](#version-computation) remains authoritative. |
+| Version base | The actual version/source used to compute the version, or the explicit initial versioning baseline. |
+| Change baseline | The release and immutable source against which the consumer delta is described, plus a source comparison link; explicitly no predecessor for an initial release. |
+| Note provenance | Release-bound PR URL or ad hoc context, its associated source identity, and snapshot time. The retained authored snapshot is the content reference, not the PR's later mutable body. |
+
+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.
+
+### 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. |
+| 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.
+
+### Correct published metadata without changing history
+
+A note correction is an audited metadata operation, not another release run:
+
+1. Establish the release-to-source and PR relationship from immutable source
+ comparisons and contemporary evidence. Preserve source-specific prerelease
+ records rather than copying a later final-PR body over them.
+2. Capture original and proposed content, reason, evidence links, actor, and
+ time in a linked audit issue or durable attached artifact. Coordinate active
+ PR ownership; do not add closing keywords to audit prose.
+3. Re-read each target before writing. If another edit changed it, reconcile the
+ correction rather than overwriting that edit. Apply only the established
+ PR/release metadata changes and retain their correspondence.
+4. Re-read the result and confirm that the correction changes no artifact,
+ asset, tag, SHA, release decision, or behavior attributed to an old version.
+ Record unverifiable facts as unresolved gaps instead of inventing actions.
+
+The audit belongs in GitHub issues and release/PR metadata, not a product
+documentation changelog. A correction to bytes still follows the
+[new-artifact recovery rule](#the-pipeline); editing notes never bypasses it.
## Release output
@@ -157,7 +293,8 @@ for an optional ad hoc dispatch. The same note is handed to
(`:` and `@`), a package in its registry. For Action,
workflow, and module artifacts the tag itself **is** the artifact.
3. A GitHub Release whose name is the version, carrying the note and the
- immutable reference (digest, package version, or the tag).
+ publication envelope, including the tag's resolved source commit and the
+ immutable artifact identity.
## Publishing targets
@@ -243,7 +380,9 @@ release, and its runs are serialised like any other.
| Surface | Where |
| --- | --- |
| Release branches + type | `.github/release.config.yml` |
-| Release decision / prerelease / RC | `release:` PR label |
+| Optional default bump | `DefaultBump` in `.github/release.config.yml` |
+| Explicit bump / prerelease / skip | `release:` PR label |
+| 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` |
| Prerelease cleanup toggle | release config / workflow input |
diff --git a/src/docs/Capabilities/release-management/index.md b/src/docs/Capabilities/release-management/index.md
index de03cc5..cf760a7 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, label-driven, versioned releases driven entirely on the GitHub platform. |
-| [Design](design.md) | How release management is built — a shared reusable workflow that reads pull-request labels, computes the SemVer bump, and cuts the release. |
+| [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. |
| [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 1f5252f..67579fd 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, label-driven, versioned releases driven entirely on the GitHub platform.
+description: Requirements for release management — automatic, policy-driven, versioned releases driven entirely on the GitHub platform.
---
# Release Management — Spec
@@ -18,7 +18,7 @@ release CLI, a hand-edited version file, or a tagging convention.
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, and the bump label records the versioning decision explicitly.
+- **[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.
- **[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
@@ -31,22 +31,31 @@ this capability governs the release. If no, there is nothing to release.
## Requirements
- **Semantic versioning.** Versions follow [SemVer 2.0.0](https://semver.org/) (`vMAJOR.MINOR.PATCH`), derived automatically — never written by hand.
-- **Namespaced release decision, stated explicitly.** Release automation reads only the `release:` namespace. Exactly one of `release:patch`, `release:minor`, `release:major`, or `release:skip` MUST be present, and there is **no default**: an unlabeled pull request is not releasable, and the release fails closed rather than assuming the smallest bump. `release:pre-release` MAY accompany exactly one bump label on an open pull request and MUST NOT be combined with `release:skip`. Bare `patch`, `minor`, and `major` labels are not release decisions. Requiring an owned label makes versioning a reviewed decision instead of an omission. Conventional commit messages are **not** required.
-- **A release per merge.** One merged PR carrying `release:patch`, `release:minor`, or `release:major` 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.
+- **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.
- **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` and a bump label 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:pre-release`, using its explicit or configured bump, and/or from a prerelease branch.
- **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 comes from the pull request title and description, or from the required release-note context of an optional ad hoc dispatch. The PR description is therefore written for consumers.
-- **Only artifact-affecting changes release.** A change that does not flow into the artifact (documentation, CI config) MUST carry `release:skip` and MUST NOT produce a release — though validation still runs on every merge.
+- **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.
- **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.
- **Recovery distinguishes retries from changed output.** Retrying validation or publication of unchanged bytes MUST reuse their artifact and version. A correction that changes the bytes MUST create a new versioned artifact; an existing version is never overwritten or reused.
- **Standard GitHub primitives only.** Pull requests, labels, comments, and, where implemented, workflow dispatch — no external tooling beyond `gh` and GitHub Actions.
+### 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.
+- **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.
+- **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
A consumer chooses how much version movement it accepts. Selecting a policy is a **consumer-side** concern — the release capability's obligation is to publish versions that make every policy expressible:
@@ -63,15 +72,21 @@ Because versions are semantic, immutable, and published once, a consumer can ado
## Success criteria
-- Merging a PR with exactly one namespaced bump label to a release branch produces a GitHub Release, a git tag, and (where one exists) a published artifact, with no manual step.
-- The version bump matches the PR's `release:` label every time; a missing, conflicting, ambiguous, or bare label set is **rejected**, never guessed.
-- An open pull request carrying `release:pre-release` and exactly one bump label publishes a prerelease without promoting it to latest.
+- 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.
- 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.
- 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.
+- 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.
## Where this connects
diff --git a/src/docs/Capabilities/vscode-extension-framework/design.md b/src/docs/Capabilities/vscode-extension-framework/design.md
index c78343c..53ccff9 100644
--- a/src/docs/Capabilities/vscode-extension-framework/design.md
+++ b/src/docs/Capabilities/vscode-extension-framework/design.md
@@ -9,8 +9,10 @@ The behaviour in the [spec](spec.md) is delivered by a **shared reusable
workflow** and a **template repository**, following the org's `Process-*` /
`Template-*` convention (as [Process-PSModule](https://github.com/PSModule/Process-PSModule)
does for PowerShell modules). A repository opts in with a short caller workflow
-and a single `.github/vscode-extension.yml` settings file; everything else has a
-secure, working default, so a minimal caller is enough to adopt it. Step logic
+and a single `.github/vscode-extension.yml` extension settings file. Build and
+test settings have secure, working defaults; release decisions follow
+[Release Management](../release-management/design.md#version-computation).
+Step logic
lives in versioned scripts the workflow calls, never inline shell.
## The pipeline
@@ -20,14 +22,16 @@ every downstream stage reuses the exact output of the stages before it:
```mermaid
flowchart LR
- find["Find version\ntags + PR label"] --> build["Build\nstamp · bundle · package VSIX"]
+ find["Find version\ntags + resolved decision"] --> build["Build\nstamp · bundle · package VSIX"]
build --> test["Test\nreal VS Code host · matrix"]
lint["Lint & type-check"] --> release
test --> release["Release\npublish the built VSIX"]
```
-- **Find version** — compute the version once, from the latest `vX.Y.Z` tag or
- release plus the pull request's bump label. Independent of the other stages.
+- **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.
+ 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
@@ -43,7 +47,7 @@ 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 PR label.
+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
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
@@ -98,12 +102,17 @@ pass before the release stage runs, alongside a green test result.
Versioning is [Release Management](../release-management/design.md) applied to a
VSIX artifact — this framework does not re-implement it:
-- The release decision is exactly one of `release:patch`, `release:minor`,
- `release:major`, or `release:skip`, with no default. Multiple bump labels and
- `release:skip` with another release label are rejected.
+- 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
+ [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` alongside one bump label on
+- A prerelease is requested by `release:pre-release` 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
@@ -165,7 +174,9 @@ 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` |
-| Version bump / prerelease | pull-request label |
+| Explicit bump / prerelease / skip | owned pull-request label |
+| Optional default bump | `DefaultBump` in `.github/release.config.yml` |
+| 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 |
| Extension manifest (`engines.vscode`, `contributes`, activation) | `package.json` |
diff --git a/src/docs/Capabilities/vscode-extension-framework/spec.md b/src/docs/Capabilities/vscode-extension-framework/spec.md
index 2e99954..c375113 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, and the bump label records the versioning decision explicitly.
+- **[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.
- **[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 settings file with secure, working defaults.** Behaviour is configured in one version-controlled settings file. Zero configuration MUST produce a correct build, test, and VSIX; every setting defaults to a secure, sensible value and is overridable in that one place.
+- **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 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.
-- **Label-driven, semantic versioning.** Versioning follows [Release Management](../release-management/spec.md): exactly one of `release:patch`, `release:minor`, `release:major`, or `release:skip` records the release decision with no default; `release:pre-release` MAY accompany one bump label. The version is [SemVer](https://semver.org/) and is derived automatically — never hand-edited in the manifest.
+- **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.
- **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.
@@ -71,8 +71,8 @@ framework itself.
## Success criteria
-- Creating a repository from the template and pushing a first change yields a green build, a passing test run, and a packaged VSIX with no configuration written.
-- A labeled pull request merged to a release branch produces a GitHub Release carrying an installable VSIX whose version matches the label's bump — a conflicting or ambiguous label set is rejected, never guessed.
+- 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.
- 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.
diff --git a/src/docs/Coding-Standards/Natural-Language.md b/src/docs/Coding-Standards/Natural-Language.md
index d3c6f13..1e25a7e 100644
--- a/src/docs/Coding-Standards/Natural-Language.md
+++ b/src/docs/Coding-Standards/Natural-Language.md
@@ -75,7 +75,7 @@ Prefer specific, observable language over vague intent.
| Prefer | Avoid |
| --- | --- |
-| The workflow fails when the version label is missing. | There may be some issues with labels. |
+| 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. |
| The agent reads `AGENTS.md` before editing files. | The agent should probably look at the instructions. |
@@ -154,7 +154,7 @@ A good error message includes:
Prefer:
```text
-Release label is missing. Add exactly one of release:patch, release:minor, release:major, or release:skip. Add release:pre-release only with a bump label.
+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.
```
Avoid:
diff --git a/src/docs/Initiatives/PSModule.md b/src/docs/Initiatives/PSModule.md
index e712f58..1a237a4 100644
--- a/src/docs/Initiatives/PSModule.md
+++ b/src/docs/Initiatives/PSModule.md
@@ -14,6 +14,15 @@ It is two things at once:
PSModule inherits the [Coding Standards](../Coding-Standards/index.md) and [Ways of Working](../Ways-of-Working/index.md) from this site and adds only what is specific to the framework. The end-to-end workflow that ships every module — [Process-PSModule](https://psmodule.io/docs/Modules/Process-PSModule/) — is documented at its canonical site.
+## Target audience
+
+| Product | Audience and supported use |
+| --- | --- |
+| PowerShell modules | PowerShell users invoking commands interactively or integrating them into scripts, pipelines, and automation. Parameters, output shapes, defaults, and runtime requirements are user-facing contracts. |
+| `PSModule/Process-PSModule` | Module maintainers using and integrating the delivery workflow into their module repositories. Caller inputs, permissions, configuration, and tool requirements are user-facing contracts. |
+
+In both cases, users are also integrators: these are roles of the same audience, not separate classes of customer. Repository READMEs [declare their audience](../Ways-of-Working/Readme-Driven-Context.md#target-audience) by adopting this definition or stating their specialization.
+
## Canonical boundary
Cross-org standards and reusable architecture are canonical in MSXOrg/docs, including:
diff --git a/src/docs/Ways-of-Working/Automation-Labels.md b/src/docs/Ways-of-Working/Automation-Labels.md
index 47c5112..83b792a 100644
--- a/src/docs/Ways-of-Working/Automation-Labels.md
+++ b/src/docs/Ways-of-Working/Automation-Labels.md
@@ -58,9 +58,13 @@ namespaced, including the release set:
These labels are read by
[release management](../Capabilities/release-management/spec.md) and by nothing else.
-Exactly one bump label or `release:skip` records the release decision.
-`release:pre-release` is an optional mode used with exactly one bump label, never
-with `release:skip`.
+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,
+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.
Reserving bare words would be weaker because it depends on a documented
prohibition rather than making ownership visible in the label itself.
@@ -81,7 +85,9 @@ label, because it teaches a contributor a rule that does not hold.
## Why not paths, states, or free text
-Labels are chosen over the alternatives because of what each one costs:
+For per-change overrides, labels are chosen over the alternatives because of what
+each one costs. Repository defaults remain version-controlled settings, not
+another label vocabulary:
| Alternative | Cost |
| --- | --- |
@@ -95,6 +101,6 @@ decision applies, and unambiguous about who acts on it.
## Where this connects
-- [Release Management](../Capabilities/release-management/spec.md) — the namespaced bump vocabulary and why exactly one of its values is required.
+- [Release Management](../Capabilities/release-management/spec.md) — the namespaced bump vocabulary, optional repository default, and required decision validation.
- [Repository Governance](../Capabilities/repository-governance/design.md) — the controls that read repository state, of which labels are one.
- [Repository Standard](Repository-Standard.md) — the repository-level requirement that labels be provisioned rather than improvised.
diff --git a/src/docs/Ways-of-Working/Branching-and-Merging.md b/src/docs/Ways-of-Working/Branching-and-Merging.md
index 2e33256..cc2bdf6 100644
--- a/src/docs/Ways-of-Working/Branching-and-Merging.md
+++ b/src/docs/Ways-of-Working/Branching-and-Merging.md
@@ -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.
-- **The bump label on it decides the production version.** Promotion is a release like any other, so the version comes from the label on this pull request, not from the versions of the changes it bundles ([release management](../Capabilities/release-management/spec.md)).
+- **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)).
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 e7f4cb5..aaa7432 100644
--- a/src/docs/Ways-of-Working/Continuous-Delivery-And-Release.md
+++ b/src/docs/Ways-of-Working/Continuous-Delivery-And-Release.md
@@ -84,24 +84,25 @@ the thing that ships. A rebuilt artifact behaves like continuous deployment —
pipeline reproduces it from a verified source, and reproducibility is what carries the
guarantee instead.
-### D2 — Version signals feed in, the label decides, at the PR gate
+### 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}
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
-[release label](Automation-Labels.md) on the pull request is authoritative, and the
-decision is taken at the pull-request gate.
+[resolved release decision](../Capabilities/release-management/design.md#version-computation)
+comes from an explicit owned label or the repository's configured default, and
+its suitability for the audience is reviewed at the pull-request gate.
-This deliberately moves the version decision **right** — off the contributing agent or
-author, onto the gate where a reviewer is already looking. An author guessing at a
-version level is guessing about consumers they cannot see; a reviewer at the gate has
-the whole change in front of them. It also means the decision is recorded on the
-artifact everyone can see, rather than inferred later from history.
+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
+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.
### D3 — Prerelease by default, stabilized on merge
-Every build from a topic branch MUST be published as a prerelease. The stable version
-is cut on merge, from the label.
+A topic-branch build authorized for release MUST be published as a prerelease.
+The stable version is cut on merge, from the resolved release decision.
A prerelease version (`1.3.0-add-widgets.1`) sorts below every stable version, which
is the entire mechanism: a consumer who has not opted in cannot resolve it, so
@@ -141,6 +142,6 @@ recorded as bad in its release notes rather than erased.
- [Continuous Practices](Continuous-Practices.md) — the wider Continuous X family and where each term comes from.
- [Release Management](../Capabilities/release-management/spec.md) — how the version decision and the prerelease flow are implemented.
-- [Automation Labels](Automation-Labels.md) — why the release label is the authoritative signal and why it is namespaced.
+- [Automation Labels](Automation-Labels.md) — why explicit release overrides use owned, namespaced labels.
- [Pre-Commit](../Coding-Standards/Pre-Commit.md) — the local half of the integration gate.
- [Branching and Merging](Branching-and-Merging.md) — the PR → main boundary the build-once decision is taken across.
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 e1bae39..c68b48b 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 exactly one change-type label are finalized. See [PR Format](PR-Format.md).
+- 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.
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/Organization-Standard.md b/src/docs/Ways-of-Working/Organization-Standard.md
index 181a4a1..fa63ff6 100644
--- a/src/docs/Ways-of-Working/Organization-Standard.md
+++ b/src/docs/Ways-of-Working/Organization-Standard.md
@@ -15,6 +15,7 @@ Each initiative must have a central documentation repository that defines its im
The initiative docs must describe:
+- The target audiences and jobs the initiative serves, including how repositories [declare or specialize that audience](Readme-Driven-Context.md#target-audience).
- Repository types used by the initiative.
- Required files for each repository type.
- Managed-file source locations and update workflow.
diff --git a/src/docs/Ways-of-Working/PR-Format.md b/src/docs/Ways-of-Working/PR-Format.md
index 04054be..72f1174 100644
--- a/src/docs/Ways-of-Working/PR-Format.md
+++ b/src/docs/Ways-of-Working/PR-Format.md
@@ -5,7 +5,13 @@ description: Pull request title, description, change types, and labels.
# PR Format
-Pull requests in the MSX ecosystem double as **release notes**. The description is written for end users of the solution, not for reviewers or developers. Implementation details go in a clearly separated technical section at the bottom.
+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
@@ -15,7 +21,7 @@ Pull requests in the MSX ecosystem double as **release notes**. The description
- 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. Never internal function names, class names, refactoring verbs.
+- 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
@@ -24,7 +30,7 @@ Pull requests in the MSX ecosystem double as **release notes**. The description
- `🩹 [Patch]: Default timeout value corrected`
- `🪲 [Fix]: Parameter validation no longer fails on null input`
- `📖 [Docs]: Installation guide updated with prerequisites`
-- `⚙️ [Maintenance]: Release workflow and dependencies updated`
+- `⚙️ [Maintenance]: Internal build tooling stays current`
### Bad titles
@@ -41,35 +47,51 @@ Pull requests in the MSX ecosystem double as **release notes**. The description
| Patch | 🩹 | `release:patch` | Small fixes or improvements |
| Fix | 🪲 | `release:patch` | Bugfixes (patch-level release impact) |
| Docs | 📖 | `release:skip` | Documentation changes only |
-| Maintenance | ⚙️ | `release:skip` | CI/CD, build configs, AI/agent files, internal upkeep |
+| Maintenance | ⚙️ | `release:skip` | Internal upkeep with no change to shipped behavior or integration contracts |
-`release:pre-release` is a release mode, not a change type. Apply it alongside
-exactly one of `release:patch`, `release:minor`, or `release:major` when an open
-pull request must publish a prerelease. Never combine it with `release:skip`.
+`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.
### Detecting the change type
+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.
+
+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.
+
The change type is decided in this order:
-1. **Explicit user input** — if the contributor / Shipper specified a type, use it.
+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. **Artifact-based inference** from the branch diff:
+3. **Find the affected consumer contracts** in the branch diff. Paths help locate evidence; they do not determine impact:
+
+ | 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. |
- | Artifact type | How to recognize | Important files (affect artifact) | Non-important (framework / tooling) |
- | ---------------------- | ------------------------------------------------------------- | -------------------------------------------------------------- | ---------------------------------------------------------------- |
- | Library / Module | `src/` with the library's source and a package manifest | `src/**`, package manifest | `.github/**`, `*.md`, `tests/**`, `scripts/**`, `agents/**` |
- | GitHub Action | `action.yml` at repo root | `action.yml`, `src/**` | `.github/**`, `*.md`, `tests/**`, `agents/**` |
- | Reusable Workflow | `.github/workflows/` with callable workflows | `.github/workflows/**` | `*.md`, `tests/**`, `agents/**` |
- | Infrastructure module | `*.tf` with input variables and outputs | `*.tf`, `*.tf.json` | `.github/**`, `*.md`, `tests/**`, `examples/**` |
+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.
-4. **Classification rules** (apply in order):
- 1. **Docs** — all changes are documentation only.
- 2. **Maintenance** — all changes are non-important for the artifact (no shipped change).
- 3. **Patch** — important-file changes are small fixes or minor improvements.
- 4. **Minor** — important-file changes add features without breaking.
- 5. **Major** — important-file changes break backward compatibility (pre-1.0.0 → downgrade to Minor).
+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.
-If the branch contains both important and non-important changes, classify based on the important changes only.
+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.
+
+Illustrative cases, not release history:
+
+| Change | Audience-based classification |
+| --- | --- |
+| 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. |
## Description structure
@@ -83,7 +105,7 @@ A concise paragraph describing **what changes for the user**. Present tense, act
Organize by **what the user experiences**, not by what was changed internally.
-- `## Breaking Changes` — what stopped working or changed incompatibly (Major only).
+- `## 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.
@@ -91,12 +113,33 @@ Organize by **what the user experiences**, not by what was changed internally.
Under each header:
- What the user can now do, or what changed for them.
-- What they need to do differently — migration steps, new parameters, changed defaults.
+- 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.
-Do **not** mention internal function names, class names, private APIs, or refactoring decisions here.
+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
+
+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.
+
+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.
-### 3. Required ending blocks
+### 4. Release impact
+
+Every PR includes `## Release impact`. Report the release resolver's decision; do not introduce a second version-selection policy.
+
+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.
+
+| 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.
+
+### 5. Required ending blocks
At the very end of every PR description, use this exact structure:
@@ -105,7 +148,17 @@ At the very end of every PR description, use this exact structure:
Technical details
-...
+### Consumer change record
+
+
+
+### Template baseline
+
+
+
+### Maintainer evidence
+
+
@@ -124,11 +177,40 @@ At the very end of every PR description, use this exact structure:
```
-The **Technical details** block is for reviewers and maintainers. Include internal implementation notes such as:
+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.
+
+#### Consumer change record
+
+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.
+
+| Identifier / surface | Before | After | Applicability / prerequisites | Consumer action | Verification |
+| --- | --- | --- | --- | --- | --- |
+| `` | `` | `` | `` | `` | `` |
+
+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.
+
+#### Template baseline
+
+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. |
+
+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.
+
+#### Maintainer evidence
+
+Keep internal implementation notes separate from the consumer record:
- Which internal functions, classes, or files were changed.
- Implementation approach and design decisions.
-- Backward compatibility notes for developers.
+- 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.
@@ -155,31 +237,52 @@ A PR that delivers a scoped Task or Bug must include at least one `Resolves` lin
## Example
+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.
+
````markdown
-Repository objects now include custom properties directly — no separate API call needed. Queries that encounter missing or inaccessible resources now return partial results with warnings instead of failing entirely.
+Job timeouts use the explicit `timeoutSeconds` setting. Existing timeout values and the 30-second default are unchanged.
-## New: Custom properties on repository objects
+## Breaking Changes
-The `repo get` command now returns custom properties inline on the repository object. Previously, retrieving custom properties required a separate `repo properties` call.
+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.
-```text
-repo get --owner MyOrg --name MyRepo --format table
-```
+## Adopting this release
-The `repo properties` command remains available if only the properties are needed.
+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.
-## Fixed: Queries no longer fail when a resource doesn't exist
+## Release impact
-Commands that query a specific repository, enterprise, or release by name now return nothing instead of throwing when the resource doesn't exist. This makes them safe to use in conditional logic without error handling.
+| 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
-- The repository model's custom-properties field is now a typed collection rather than an untyped object.
-- The GraphQL query layer splits error handling into partial-success (data + errors → warnings) and full-failure (errors only → terminating error) branches.
-- Null guards added to the repository lookup helpers.
-- Implementation plan progress: tasks 1–3 in Org/Repo#218 completed; task 4 (integration tests) remains.
+### Consumer change record
+
+| 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. |
+
+### Template baseline
+
+Not applicable: this product does not distribute an integration template.
+
+### Maintainer evidence
+
+- 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.
+
+| Changed surface | Standards checked | Framework docs checked | Result |
+| --- | --- | --- | --- |
+| Configuration parsing and timeout behavior | Naming, Error Handling, Testing | Product configuration contract | Aligned |
@@ -187,7 +290,6 @@ Commands that query a specific repository, enterprise, or release by name now re
Relevant issues (or links)
- Resolves Org/Repo#218
-- Resolves Org/Repo#219
### Related work
@@ -196,6 +298,8 @@ Commands that query a specific repository, enterprise, or release by name now re
````
+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.
@@ -211,7 +315,7 @@ Commands that query a specific repository, enterprise, or release by name now re
## Labels and assignment
-- Apply the change-type label.
+- 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.
diff --git a/src/docs/Ways-of-Working/Readme-Driven-Context.md b/src/docs/Ways-of-Working/Readme-Driven-Context.md
index bd38f9a..d495da8 100644
--- a/src/docs/Ways-of-Working/Readme-Driven-Context.md
+++ b/src/docs/Ways-of-Working/Readme-Driven-Context.md
@@ -32,6 +32,14 @@ Include what is relevant. Not every repository needs every section.
For simple repositories (e.g., a single GitHub Action), a subset is fine — at minimum the title, description, and usage sections.
+## Target audience
+
+Every repository README MUST identify its target audience, the jobs the product helps them do, and the supported interfaces they use. A short statement in the description is enough; a separate persona document is not required. A repository MAY explicitly adopt and link its initiative's audience definition instead of repeating it, and MUST state any repository-specific specialization.
+
+**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.
+
## When to update the README
The README is updated **in the same pull request** that introduces the change. Documentation is part of the work — not a separate follow-up.
@@ -43,7 +51,7 @@ The README is updated **in the same pull request** that introduces the change. D
- A feature, command, or option is removed or deprecated.
- Installation or setup steps change.
- Configuration options change.
-- The project scope or purpose evolves.
+- The project scope, purpose, target audience, or supported uses evolve.
- Architecture or folder structure changes significantly.
### Do not update for
diff --git a/src/docs/Ways-of-Working/Repository-Standard.md b/src/docs/Ways-of-Working/Repository-Standard.md
index 3c039f1..1bbc6b9 100644
--- a/src/docs/Ways-of-Working/Repository-Standard.md
+++ b/src/docs/Ways-of-Working/Repository-Standard.md
@@ -23,7 +23,7 @@ discoverability minimum defined below instead.
| File | Requirement |
| --- | --- |
-| `README.md` | Acts as the repository start page: purpose, value, access, first mental model, and where to go next. |
+| `README.md` | Acts as the repository start page: purpose, target audience, value, access, first mental model, and where to go next. |
| `LICENSE` | States the legal terms for reuse and redistribution. |
| `.github/CONTRIBUTING.md` | Explains how to contribute, including how the organization defaults and central pull request template apply. |
| `AGENTS.md` and its client routes | Route every agent runtime from this repository's own files outward to the initiative and central documentation. [Agentic Development](../Capabilities/agentic-development/design.md#client-behavior) names the files and the path each one sits at. |
@@ -81,6 +81,7 @@ A README answers these questions, in this order:
| Question | README responsibility |
| --- | --- |
| What is it? | Name the product or artifact and its scope. |
+| Who is it for? | State the [target audience and supported uses](Readme-Driven-Context.md#target-audience), or explicitly adopt the initiative's definition and state any specialization. |
| Why should I care? | State the value or problem it solves. |
| How do I get it? | Show the shortest install, download, import, or usage entry point. |
| How does it work? | Give a concise introduction to the main capability or operating model. |
@@ -173,7 +174,7 @@ Default title pattern:
[]:
```
-The description should lead with user-facing impact, continue with user-facing change sections, include optional technical details after those sections, and end with the related-issues block. It closes one scoped Task or Bug as required by [PR Format](PR-Format.md), with any additional closing links limited to issues the session-end convergence sweep shows are fully delivered by the same diff.
+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.
The organization-level `.github` repository supplies the default template.
The repository-local contribution guide directs humans and agents to the
diff --git a/src/docs/Ways-of-Working/Workflow-Stages/Implement.md b/src/docs/Ways-of-Working/Workflow-Stages/Implement.md
index e3096ac..021b485 100644
--- a/src/docs/Ways-of-Working/Workflow-Stages/Implement.md
+++ b/src/docs/Ways-of-Working/Workflow-Stages/Implement.md
@@ -83,7 +83,7 @@ Run this once per implementation session, at the same timing as the standards/fr
When the change meets the [Definition of Ready for Review](../Definition-of-Ready-and-Done.md):
-1. Finalize the title, release-note description, and label per [PR Format](../PR-Format.md).
+1. Finalize the title, release-note description, and effective release decision and its source per [PR Format](../PR-Format.md).
2. Mark the pull request ready and enable auto-merge per [Branching and Merging](../Branching-and-Merging.md).
## Operating rules