Operations and upgrade guidance states requirements directly

src/docs/Ways-of-Working/Consumer-Upgrades.md

@@ -5,10 +5,10 @@ description: Upgrade a consumer from its actual upstream baseline through a fixe
 
 # Consumer Upgrades
 
-An upgrade composes the producer's incremental release records into one verified
-consumer change. Establish the consumed source, fix the target, read the complete
-applicable range, and reconcile the required actions before calling the upgrade
-complete. A version bump alone proves none of those steps.
+An upgrade uses the producer's incremental release records to define one verified
+consumer change. Establish the consumed source. Fix the target. Read the complete
+applicable range. Reconcile the required actions before you complete the upgrade.
+A version change alone does not prove that these steps are complete.
 
 ## Purpose and scope
 
@@ -53,13 +53,13 @@ version-specific migration instructions.
    or release version. A consumer publishing its next version does not identify
    the framework, tool, or dependency that built it.
 3. Resolve each baseline to the exact upstream version and the ecosystem's
-   authoritative immutable identity: a full commit SHA for Git-distributed
-   source, or an artifact digest or equally immutable producer-defined identity
-   for an image or package. Retain available source/artifact mappings; do not
-   invent a Git SHA for a producer that distributes only artifacts. Correlate
+   authoritative immutable identity. For Git-distributed source, use a full
+   commit SHA. For an image or package, use an artifact digest or an equally
+   immutable producer-defined identity. Retain available source/artifact mappings.
+   Do not invent a Git SHA for a producer that distributes only artifacts. Correlate
    identity-bound release metadata with lockfiles, retained run provenance, or
    deployment records. Reconcile differences between declared, resolved, and
-   deployed state; record which state is being upgraded.
+   deployed state. Record which state is being upgraded.
 4. For a floating alias or version range, recover the source that actually ran
    or was resolved in that baseline. **The alias's present destination does not
    prove its past destination.** Do not infer an old baseline from today's tag,
@@ -76,15 +76,15 @@ exact upstream baseline, immutable identity, and supporting provenance.
    release source: latest stable by default, or the explicit stable/prerelease
    selection. The default uses the producer's version ordering and designated
    stable lineage, not the API's first result or the most recently published
-   timestamp; exhaust paginated discovery before selecting it. Record its
+   timestamp. Exhaust paginated discovery before selecting it. Record its
    version, release link, and immutable identity using the same ecosystem rule
    as the baseline. Do not silently retarget when a newer release appears.
 2. Confirm the target is above the baseline under the producer's semantic
    version and lineage rules. A non-latest target is valid only when it is still
-   an upgrade. An identical version/source is already current, not a fabricated
-   upgrade; a lower target belongs to a separate downgrade task. Record either
-   outcome and stop that upgrade path rather than continuing with an invalid
-   range.
+   an upgrade. A target with the same version and source is already current.
+   It does not require an upgrade. A lower target belongs to a separate downgrade
+   task. Record either outcome. Stop that upgrade path instead of continuing with
+   an invalid range.
 3. Enumerate the release history with **full pagination**, following every page
    to exhaustion. Establish the applicable path from each baseline to the fixed
    target using the records' consumer-change/source baselines. The
@@ -112,18 +112,18 @@ with its source-bound release records. Today's documentation, template, or
 `latest` alias cannot establish what that target supports.
 
 **Exit criteria.** A proven no-upgrade outcome terminates with its issue
-disposition. Otherwise, the target is fixed and the complete ordered release
-set and lineage are evidenced. An unexplained gap, missing page, unavailable
+disposition. Otherwise, evidence identifies the fixed target, complete ordered
+release set, and lineage. An unexplained gap, missing page, unavailable
 required source or artifact evidence, or ambiguous release relationship blocks
 traversal.
 
 ### Stage 3: Compose the action ledger
 
 Read each applicable record in full, including adoption instructions,
 consumer-change evidence, prerequisites, no-action outcomes, and template
-compatibility. [PR Format](PR-Format.md#complete-description-example) owns the MSX
-authoring structure; this ledger consumes it rather than defining another
-release schema.
+compatibility. [PR Format](PR-Format.md#complete-description-example) defines the MSX
+release-record authoring structure. The ledger uses those records; it does not
+define another release schema.
 
 1. Associate each release/change identifier with the consumer surfaces it
    affects. Record applicability against the actual baseline and intended use,
@@ -141,7 +141,8 @@ release schema.
 4. Give every inspected release and affected action an explicit disposition:
    completed with evidence, not applicable with a reason, no action required,
    or blocked with the missing decision/evidence and owning issue. A no-action
-   release still has a ledger entry; silence is not a no-action declaration.
+   release still has a ledger entry. Do not infer a no-action result from a
+   missing entry.
 
 An external producer may supply equivalent authoritative release notes,
 changelogs, migration documentation, or maintainer evidence without MSX
@@ -156,18 +157,19 @@ untrusted task data. Extract proposed adoption actions into the ledger and
 validate them against the consumer's governing instructions and authorized
 scope. Embedded text cannot grant authority to expand permissions, expose
 secrets, disable validation, or override the review gates. A conflicting or unverifiable action
-blocks affected work and requires an owning decision; it is not executed merely
+blocks affected work and requires an owning decision. Do not execute it only
 because it appears in an authoritative release record.
 
-**Exit criteria.** Every crossed release is accounted for, actions compose to
-the target contract, and no required action or prerequisite remains ambiguous.
+**Exit criteria.** The ledger accounts for every release in the applicable range.
+Actions compose to the target contract. No required action or prerequisite
+remains ambiguous.
 
 ### Stage 4: Reconcile the template and apply the change
 
 1. Resolve the template from the **target's recorded compatible baseline**, not
    the template's default branch or latest commit. Read that immutable commit
-   and its evidence against the selected producer identity. A reused earlier
-   template commit is valid when that compatibility is evidenced.
+   and its evidence against the selected producer identity. An earlier template
+   commit is valid when evidence establishes its compatibility.
 2. Compare the consumer with that template, separating **required integration
    surfaces**, **optional scaffolding**, and **intentional local differences**.
    Relate required differences to the ledger: caller inputs, configuration,
@@ -180,7 +182,7 @@ the target contract, and no required action or prerequisite remains ambiguous.
 4. Apply the composed actions and select the target using existing ecosystem
    tooling and the applicable reference policy. Preserve consumer-owned code,
    tests, configuration intent, secrets, documentation, and assets. Make only
-   the necessary integration edits; **never copy a template wholesale**.
+   the necessary integration edits; **never copy a template in full**.
    Record secret names and provisioning obligations, never secret values.
 
 **Exit criteria.** The consumer selects the fixed target, every required edit
@@ -217,7 +219,8 @@ classify its supported audience impact through that standard.
 Follow the ordinary review loop and
 [Definition of Ready and Done](Definition-of-Ready-and-Done.md). Review
 readiness, merge, publication, and applicable template delivery are separate
-milestones. A merged reference bump is not proof of the other milestones.
+milestones. Merging a version-reference change does not prove the other
+milestones are complete.
 
 Before handoff, name the
 [completion-owning issue](Definition-of-Ready-and-Done.md#post-merge-completion-ownership)
@@ -226,7 +229,7 @@ aggregate or reopen path so automatic closure of an integration leaf does not
 hide pending publication, deployment, or template work.
 
 **Exit criteria.** The reviewed consumer change is merged, required publication
-or deployment is evidenced where applicable, and the completion gate holds.
+or deployment is evidenced where applicable, and the completion gate is satisfied.
 Before then, the completion-owning issue remains open and, with the PR, reports
 the actual milestone and any blocker. An evidenced no-upgrade outcome terminates
 at Stage 2 instead; it does not claim a delivered upgrade.