🚀 [Feature]: Consumer upgrades use complete release-range evidence

.github/plugin/README.md

@@ -32,6 +32,18 @@ plugin uses `msx-coding-*` skills for each coding language or tool,
 index. Skill bodies do not copy the documentation; they identify the one page
 to read.
 
+## Consumer upgrades
+
+`msx-ways-of-working-consumer-upgrades` points to the shared
+[Consumer Upgrades](../../src/docs/Ways-of-Working/Consumer-Upgrades.md)
+procedure. It is a discovery shortcut, not a prerequisite for following the
+procedure or a bundle of migration instructions.
+
+Source/version discovery and compatible immutable template identity remain
+producer-owned. Initiative documentation and plugins supply those entry points
+under the [marketplace ownership boundary](../../src/docs/Capabilities/agentic-development/design-plugin-marketplaces.md#consumer-upgrade-discovery);
+the shared skill supplies only the common method.
+
 ## Versions
 
 Keep the plugin version in `plugin.json` synchronized with the version of its

.github/plugin/marketplace.json

@@ -10,8 +10,8 @@
   "plugins": [
     {
       "name": "msx",
-      "description": "Routes coding, documentation, and work lifecycle tasks to current MSX standards.",
-      "version": "0.1.0",
+      "description": "Routes coding, documentation, consumer upgrades, and work lifecycle tasks to current MSX standards.",
+      "version": "0.2.0",
       "source": ".github/plugin/msx"
     }
   ]

.github/plugin/msx/plugin.json

@@ -1,8 +1,8 @@
 {
   "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
   "name": "msx",
-  "version": "0.1.0",
-  "description": "Routes coding, documentation, and work lifecycle tasks to current MSX standards.",
+  "version": "0.2.0",
+  "description": "Routes coding, documentation, consumer upgrades, and work lifecycle tasks to current MSX standards.",
   "author": {
     "name": "MSXOrg",
     "url": "https://github.com/MSXOrg"
@@ -11,6 +11,7 @@
   "repository": "https://github.com/MSXOrg/docs",
   "keywords": [
     "coding-standards",
+    "consumer-upgrades",
     "documentation",
     "github-copilot",
     "msx",

.github/plugin/msx/skills/msx-ways-of-working-consumer-upgrades/SKILL.md

@@ -0,0 +1,8 @@
+---
+name: msx-ways-of-working-consumer-upgrades
+description: Apply the MSX consumer upgrade procedure when upgrading an upstream dependency or framework.
+---
+
+# Upgrade an MSX consumer
+
+Read and follow [MSX Consumer Upgrades](https://github.com/MSXOrg/docs/blob/main/src/docs/Ways-of-Working/Consumer-Upgrades.md).

src/docs/Capabilities/agentic-development/design-plugin-marketplaces.md

@@ -28,6 +28,23 @@ only provides organization defaults.
 Each skill points to one canonical document. Its body may include runtime
 mechanics, but it MUST NOT duplicate the procedure or define a second workflow.
 
+### Consumer upgrade discovery
+
+The shared `msx-ways-of-working-consumer-upgrades` skill points only to
+[Consumer Upgrades](../../Ways-of-Working/Consumer-Upgrades.md). The procedure
+works without an installed plugin; the skill is a discovery shortcut.
+
+| Owner | Owns |
+| --- | --- |
+| MSX shared documentation and plugin | The version-independent upgrade method and its common evidence/completion gates. |
+| Producer or initiative documentation and plugin | Authoritative source and registry locations, version and release-lineage discovery, target-era guidance, and the mapping to a compatible immutable template commit or explicit no-template result. |
+
+An initiative entry point routes to that producer-owned discovery, then uses the
+shared procedure. It does not move initiative-specific authority into the
+shared skill or package a version-specific migration cookbook. Target template
+identity comes from source-bound release evidence, not the installed plugin
+version or today's template branch.
+
 ## Layout and names
 
 Each owning repository uses this layout:

src/docs/Capabilities/agentic-development/plugin-distribution.md

@@ -90,6 +90,12 @@ The [Plugin Marketplaces design](design-plugin-marketplaces.md) is the single so
 for marketplace ownership, repository layout, plugin identities, and skill granularity. This
 page covers how named intents are distributed; it does not repeat those structural rules.
 
+For consumer upgrades, `msx-ways-of-working-consumer-upgrades` is the shared
+pointer to [Consumer Upgrades](../../Ways-of-Working/Consumer-Upgrades.md).
+Initiative entry points supply producer-owned discovery under the
+[upgrade discovery boundary](design-plugin-marketplaces.md#consumer-upgrade-discovery),
+not a second migration procedure.
+
 ## GitHub Copilot distribution
 
 An individual registers the marketplace and installs its standards plugin with Copilot CLI:

src/docs/Capabilities/dependency-updates/design.md

@@ -68,21 +68,38 @@ bad now, and waiting for a schedule window or a cooldown would be waiting on pur
 ## The updater
 
 The updater opens **one PR per outdated or vulnerable dependency**, carrying the
-change and the upstream release notes. SHA-pinned dependencies get the new
+proposed reference change and upstream release context. SHA-pinned dependencies get the new
 commit SHA with the version as a trailing comment. Ecosystems, directories, and
 schedule live in `.github/dependabot.yml`; a non-default
 cooldown belongs there too, while the standard three-day cooldown remains
 implicit.
 
 ```mermaid
 flowchart TD
-  check["Scheduled check / advisory"] --> pr["Open dependency update PR"]
-  pr --> ci["Required checks run<br/>(same gate as any PR)"]
+  check["Scheduled check / advisory"] --> pr["Open dependency update PR<br/>ensure draft state"]
+  pr --> adoption["Consumer Upgrades<br/>(full range + actions + template)"]
+  adoption --> ci["Required checks run<br/>(including adoption evidence)"]
   ci --> review["Review and merge"]
   review --> merged["Merged"]
   merged --> release["Separate release decision<br/>see Release Management"]
 ```
 
+### Complete the adoption
+
+The updater's proposal is an input, not proof that the consumer is upgraded.
+The author or delegated agent completes
+[Consumer Upgrades](../../Ways-of-Working/Consumer-Upgrades.md) in that same
+delivery: establish the actual consumed source, fix the proposed target, and
+inspect the entire applicable range with full pagination and semantic/lineage
+ordering. An embedded newest note does not replace earlier crossed releases.
+
+The procedure owns action composition, target-era template comparison,
+preservation of consumer intent, and existing validation, including no-action
+ranges. Its reconciled evidence belongs in the update PR. If the updater
+omits required context, retrieve equivalent authoritative producer evidence;
+otherwise register the gap and keep affected work blocked. This adds an
+adoption obligation to the existing review path, not another updater.
+
 ### Release decision
 
 Dependency changes are collected before the repository release decision is
@@ -92,7 +109,29 @@ Management](../release-management/design.md).
 ## Review and merge
 
 Every automated update passes the repository's normal review and required-check
-gates. Automatic merge, where configured, never bypasses those gates.
+gates, including [complete consumer evidence](../../Ways-of-Working/Definition-of-Ready-and-Done.md#definition-of-ready-for-review).
+Required migration work cannot be deferred while merging an incompatible
+reference bump. Automatic merge, where configured, never bypasses those gates.
+
+Bind adoption verification to the
+[required-check signal](../merge-automation/design.md#the-gate-a-ruleset-requires-the-checks)
+before enabling automatic readiness, approval, or merge for update PRs.
+An existing required PR validation check can carry this condition; a separate
+check is needed only when no existing check owns it. Missing or stale
+range/ledger/template evidence keeps the result pending or failed, even when
+build and test checks are green. Re-evaluate the result when the candidate or
+its required evidence changes.
+
+Create update PRs as drafts. If the native updater cannot do that, the receiving
+workflow immediately converts each opened proposal to draft, before requesting
+human review. Keep it draft until the normal review-readiness gate, including
+adoption verification, holds. The draft flag is the review-handoff signal; it
+does not replace the binding required check or protect the creation-to-conversion
+window by itself.
+
+Until evidence verification is enforced through the required check, update PRs
+remain outside automated readiness, approval, and merge. The platform updater
+supplies a proposal; it does not assert that the gate has passed.
 
 ## Security updates
 
@@ -120,6 +159,7 @@ rather than overwrite.
 ## Where this connects
 
 - [Spec](spec.md) — the requirements this design delivers.
+- [Consumer Upgrades](../../Ways-of-Working/Consumer-Upgrades.md) — the procedure that turns an update proposal into verified adoption.
 - [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.
 - [Downstream Release Propagation](../downstream-release-propagation/design.md) — the internal counterpart; propagation PRs are dependency updates too.

src/docs/Capabilities/dependency-updates/spec.md

@@ -31,8 +31,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
+Adopting the dependency includes the integration changes it requires, not just
+changing its reference. Selecting and publishing the consumer repository's own
+release remains out of scope and is governed by [Release
 Management](../release-management/spec.md).
 
 ## Requirements
@@ -68,15 +69,31 @@ 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.
+- **FR10 — One reviewed pull request per update.** Each dependency update is a pull request that stays draft until the normal review-readiness gate holds and 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).
 - **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.
+- **FR14 — Adoption covers the complete upgrade.** Each proposed upgrade MUST
+  satisfy [Consumer Upgrades](../../Ways-of-Working/Consumer-Upgrades.md) from
+  the consumer's actual immutable upstream baseline through its fixed target.
+  Required integration actions, applicable template differences, and relevant
+  consumer validation MUST be reconciled before review readiness. Missing
+  evidence or a required action MUST block affected work, not become an
+  optional follow-up. Before an update is eligible for automatic readiness,
+  approval, or merge, verification of that evidence MUST be represented by a
+  required PR check. A missing, stale, pending, or failed result MUST hold the
+  update even when its other checks pass.
 
 ### Non-functional
 
 - **NFR1 — SHA pins stay immutable.** An update to a SHA-pinned dependency rewrites the pin to the new commit SHA and records the human-readable version alongside it, so the pin stays exact and stays legible.
-- **NFR2 — Update pull requests carry their evidence.** Each one includes the upstream release notes or changelog for the range it crosses. A reviewer deciding on a bump should not have to leave the pull request to find out what changed.
+- **NFR2 — Update pull requests carry their evidence.** Each one includes the
+  complete applicable upstream release evidence for the range it crosses,
+  exact source identities, and the reconciled action/template and validation
+  results required by [Consumer Upgrades](../../Ways-of-Working/Consumer-Upgrades.md#outputs-and-evidence).
+  The newest note or an updater's summary alone is insufficient; no-action
+  releases remain accounted for. Equivalent authoritative external evidence
+  does not need MSX formatting.
 - **NFR3 — The mechanism is platform-native.** Checking, advisory correlation, and pull request creation are platform functions, not bespoke automation, so no repository maintains an updater of its own.
 
 ## Success criteria
@@ -85,10 +102,17 @@ Management](../release-management/spec.md).
 - 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.
 - No dependency pull request merges without passing the same checks as any other pull request.
+- An update that skips releases still accounts for every applicable increment,
+  and a no-action patch retains explicit evidence and relevant validation.
+- Missing baseline, action, or applicable template evidence leaves the affected
+  update blocked with a linked owning issue.
+- An updater-created PR with green build checks but incomplete adoption
+  evidence cannot be automatically marked ready, approved, or merged.
 
 ## Where this connects
 
 - [Design](design.md) — the updater, review, and automatic-merge policy.
+- [Consumer Upgrades](../../Ways-of-Working/Consumer-Upgrades.md) — the shared adoption procedure and complete-range evidence.
 - [Release Management](../release-management/spec.md) — the 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.