Define the evergreen consumer upgrade procedure and completion gates

[MariusStorhaug]

Context and request

Give humans and agents one version-independent procedure for upgrading a consumer from its actual upstream baseline through a resolved target, using the complete crossed release history and an applicable immutable template baseline. Producer-owned guides supply source/version/template discovery; installing a skill is not a prerequisite.

The procedure consumes the incremental release evidence established by MSXOrg/docs#202. Its native dependency records that prerequisite. This Task delivers the common procedure and its connected gates in one MSXOrg/docs PR; it does not execute the PSModule pilot or edit release history.

Acceptance criteria

• A reader can discover the common procedure through the Ways of Working index, fleet guidance, dependency updates, downstream propagation, and the shared agent plugin.
• The procedure identifies each consumed upstream reference, distinguishes it from the consumer's own package version, and resolves an exact version and immutable source identity. A floating alias's present destination is not evidence of what previously ran.
• The target is resolved and recorded once: latest stable by default, or an explicit stable/prerelease target. An older-than-latest target remains an upgrade from the baseline; downgrades are a separate operation.
• Traversal reads every applicable release after the baseline through the target, baseline-exclusive and target-inclusive, with full pagination and semantic/lineage ordering rather than API order or timestamps. It excludes unrelated backports and prerelease streams; no-action releases are still inspected.
• An applicability-aware action ledger composes renamed, superseded, and reversed changes and retains genuinely required intermediate steps. Missing baseline provenance, release evidence, required actions, or applicable template compatibility blocks affected work and registers an upstream gap. Equivalent authoritative evidence from an external producer is accepted without requiring MSX formatting.
• Upgrades preserve consumer-owned code, tests, configuration intent, secrets, documentation, and assets. The target template comparison distinguishes required integration surfaces from optional scaffolding and intentional local differences; it never copies a template wholesale. Products without a template explicitly record that fact.
• Existing relevant consumer validation and ledger reconciliation establish the result, including no-op ranges. The upgrade PR records exact range/source identities, release links, completed and not-applicable actions, target-template evidence and differences, outcomes, and unresolved blockers. Older targets use immutable historical source/docs and release records, not today's docs or template.
• Review readiness requires complete consumer release evidence. Applicable producer work is not done until compatible immutable template evidence exists and necessary linked template changes are delivered. Review, merge, publication, and template completion remain distinct; immutable candidate/prerelease evidence avoids circular pre-merge requirements when final template wiring needs the released producer version.
• Product documentation describes the current contract, while per-release changes and delivery plans live in issues, PRs, and releases. Decision records and research artifacts remain supported exceptions.
• The shared skill is a thin pointer. Initiative-specific source/version/template discovery stays in initiative documentation and plugins. Plugin and marketplace-entry versions move together, and navigation, generated indexes, and discovery docs agree.

Merged contract and kickoff

Use a fresh session/worktree from main containing MSXOrg/docs#204, merged as 702be0fa7db80a5e24eb9ebc47badc017356257b. Read the current canonical pages rather than carrying forward the completed session's transcript or reusing its feature branch.

The merged contract already defines incremental PR/release evidence, audience-based classification, immutable template/source evidence, and opt-in DefaultBump with no implicit patch fallback. Missing decisions must fail a required pre-merge CI check. Preserve those rules; this Task adds the common consumer procedure and its consumer-evidence/producer-template completion gates rather than creating another release resolver or duplicating the existing schema.

At handoff, MSXOrg/docs#166 remains open for required CI enforcement, and MSXOrg/docs#196 remains open with an implicit-patch proposal that differs from the merged contract. Re-check both before acting; do not treat the previous merge as proof that protection is enforced, import a conflicting policy, or edit another active branch without coordinating ownership. These are separate concerns, not extra implementation scope for this Task.

Read complete review summaries, including suppressed comments: zero new inline comments alone is not evidence that a review is clean. Producer CI/ruleset implementation, the PSModule pilot, and historical backfill remain separately scoped.

Technical decisions

Surface	Change
src/docs/Ways-of-Working/Consumer-Upgrades.md	Add the canonical staged procedure using the orchestration-playbook template: scope, inputs, ordered stages, stop conditions, durable evidence, and completion.
src/docs/Ways-of-Working/Definition-of-Ready-and-Done.md	Add consumer-evidence review readiness and producer/template completion obligations without duplicating the playbook.
src/docs/Ways-of-Working/Workflow-Stages/Implement.md	Link the existing alignment pass to the gate; do not introduce a second checklist.
src/docs/Ways-of-Working/Documentation-Model.md	Clarify current-product versus release/history/delivery-plan ownership while preserving decision and research tiers.
src/docs/Ways-of-Working/Fleet-Orchestration.md	Route per-consumer upgrades through the common procedure.
src/docs/Capabilities/dependency-updates/{spec,design}.md and src/docs/Capabilities/downstream-release-propagation/{spec,design}.md	Link full-range adoption obligations; receiving the newest note does not replace inspection of the consumer's crossed range.
src/docs/Capabilities/agentic-development/design-plugin-marketplaces.md	Distinguish shared method from initiative-owned authority, discovery, and compatible template identity.
.github/plugin/msx/skills/msx-ways-of-working-consumer-upgrades/SKILL.md	Add a thin pointer to the canonical procedure, not embedded migration instructions.
src/zensical.toml, generated indexes, .github/plugin/README.md, and applicable plugin discovery/manifests	Wire discovery; increment the shared plugin and its marketplace-entry version together.

Use structured Markdown and existing documentation/plugin patterns. No release-history file, migration cookbook, updater, publisher implementation, automatic template synchronizer, version-specific skill, or pilot-consumer change belongs in this PR. Re-read the prerequisite's merged contract at implementation kickoff and coordinate any overlapping active PR before editing its scope.

Implementation plan

• Read the prerequisite's completed PR and canonical orchestration-playbook, readiness, documentation, dependency-update, propagation, and plugin guidance. Define walkthrough expectations for no-action patch, breaking transition, skipped releases, prerelease target, non-latest target, ambiguous floating baseline, and missing evidence/template cases.
• Write Consumer-Upgrades.md and connect the existing readiness, completion, alignment, documentation-model, and fleet surfaces to its single procedure.
• Check the dependency-update and propagation flows against the walkthroughs, then update their spec/design pairs and the plugin-marketplace design without implementing their automation.
• Inspect tests/PluginMarketplace.Tests.ps1 before adding the thin skill. Wire navigation/discovery, synchronize plugin/marketplace versions, and regenerate indexes with .github/scripts/Update-DocumentationIndex.ps1.
• Run the existing index check, relative-link and applicable cross-repository-link checks, targeted Markdown linting, and the existing plugin test suite. Use .github/scripts/Invoke-PesterSuite.ps1 if its pinned dependency setup is needed; introduce no new validation toolchain.
• Reconcile every walkthrough and ledger/stop condition, record standards/framework alignment and scoped issue convergence in the PR, and complete the normal review gates.

Delivery boundary

Keep one scoped Task per PR, small logical commits, push each commit, and open a draft early. The PSModule pilot is separately refined after the MSX contract: confirm the consumer's immutable baseline, reconcile existing producer/template work, repair the pilot's crossed release chain, and prove two target cases before complete historical backfill. Neither pilot execution nor bulk historical metadata writes are authorized by this Task.

[MariusStorhaug]

Delivery A merged in #204 and its delivery leaf is closed. Added the merged baseline and the final contract decisions to this Task so a fresh session can implement Delivery B from main without the previous transcript. The native dependency remains the source of execution order. Scope is unchanged: one common-procedure/docs/plugin PR, not pilot execution, publisher implementation, or historical writes.

[MariusStorhaug]

Delivery B kickoff is isolated on consumer-upgrades from remote main at 702be0fa7db80a5e24eb9ebc47badc017356257b; the prerequisite merge is an ancestor of HEAD. Read #203 including comments and its native blocked-by edge to closed #202, merged #204 and its complete reviews (including suppressed concerns), and the current canonical procedure, release-evidence, plugin, and validation guidance. There is no native parent. No completed-session branch is reused.

Rechecked adjacent work: #166 remains open, and the effective main rules contain deletion, non-fast-forward, linear-history, and pull-request rules but no required status checks. #196 remains open with the implicit-patch proposal; its changed files do not overlap this Task's planned edits. Neither its branch nor repository governance is changed. Delivery A's audience classification, complete incremental evidence, explicit/default decision precedence, no implicit patch, and merge-blocking validation requirement remain authoritative.

Walkthrough expectations established before implementation:

Case	Required outcome
No-action patch / no template	Inspect and record the release, justify no template, select the exact target, and reconcile existing validation and the no-action ledger.
Breaking transition	Apply audience-relevant migration and required integration surfaces without replacing consumer-owned content.
Skipped releases	Read all pages in semantic/lineage order; compose renames, reversals, and supersession while retaining required intermediate steps and excluding unrelated backports.
Explicit prerelease	Retain its immutable source-specific record and stream, not later final-PR content or unrelated prereleases.
Non-latest stable target	Confirm it is still an upgrade and use immutable target-era sources, docs, and template; no silent retarget or downgrade.
Ambiguous floating baseline	Recover actual prior execution provenance; the alias's present destination is not evidence. Block unresolved provenance.
Missing release/action/template evidence	Stop affected work and register the owning gap; accept equivalent authoritative external evidence without MSX formatting.
Producer/template sequencing	Verified immutable candidates permit review without pretending final wiring is delivered; producer completion waits for the necessary linked template delivery and actual-source compatibility evidence.

Implementation starts with the canonical playbook and navigation, followed by connected gates/capability contracts and the thin shared skill. One draft PR closes only #203; no pilot execution, publisher implementation, or historical metadata writes.

[MariusStorhaug]

The canonical playbook and navigation are in 39a6874; the next pushed commit connects consumer-evidence review readiness, immutable candidate/template evidence, post-publication producer/template completion, the existing Implement alignment pass, current-product versus release-history ownership, and per-consumer fleet adoption. The fleet example now delegates migration discovery instead of prescribing a version-specific test migration. #205 is the single draft delivery PR. Relative links and targeted Markdown checks pass; capability and plugin wiring follow. Auto-merge remains disabled.

[MariusStorhaug]

The dependency-update and downstream-propagation spec/design pairs now route adoption through the common full-range procedure. Update proposals and received notes are inputs, not evidence of completed adoption; required gaps block rather than become optional follow-ups. Propagation stays stable-only, retains its event/backfill target, and does not downgrade a consumer that has moved ahead. The marketplace design separates shared method from producer-owned authority, version/source discovery, and compatible immutable template identity. These are documentation contracts, not updater or publisher implementations. The initial Copilot review (including its suppressed concern) identified the remaining planned wiring; the connected-gate thread is addressed by 25b90fe, and plugin discovery is next.

[MariusStorhaug]

The shared msx-ways-of-working-consumer-upgrades skill is an eight-line thin pointer to the canonical playbook. Plugin discovery documentation is wired, and the shared plugin plus its marketplace entry move together from 0.1.0 to 0.2.0; catalog metadata remains independently versioned. Existing plugin identities and procedures are unchanged. Index regeneration/check and relative links pass (128 documentation files). Targeted Markdown lint passes for all 14 changed Markdown files. Cross-repository validation passes for the existing repository scope (7 links) and applicable changed-file/skill scope (1 link across 14 files). The existing runner imported pinned Pester 6.0.1 with its expected GUID and passed all four tests in tests/PluginMarketplace.Tests.ps1; no dependency or validation toolchain was added. Final walkthrough, alignment/convergence evidence, and complete Copilot review reconciliation remain before handoff.

[MariusStorhaug]

Documentation walkthroughs are reconciled against the playbook and connected gates. These are illustrative contract cases, not a PSModule pilot or claims that a real consumer was upgraded:

Walkthrough	Result required by the documented stages
No-action patch, 1.2.0 -> 1.2.1	The sole crossed release remains in the ledger with explicit no-action evidence. Reference selection still requires existing consumer validation and its actual tested identity.
Breaking transition, 1.9.0 -> 2.0.0	A required timeout -> timeoutSeconds change preserves the consumer's value and other local intent. Optional template scaffolding, tests, documentation, assets, and secrets are not replaced. Pre-1.0 version classification does not hide breaking behavior.
Skipped releases on two out-of-order pages	The applicable 1.1.0, 1.2.0, 1.3.0, 2.0.0 sequence is read after baseline 1.0.0; an unrelated maintenance-line 1.0.1 is excluded with lineage evidence. A -> B -> C composes to A -> C when direct adoption is supported; reversed flag changes can net to no edit, but a required data conversion remains. No-action 1.3.0 is retained.
Explicit prerelease, 2.0.0-rc.2 -> 2.0.0-rc.10	Numeric prerelease ordering, intervening applicable records, and source-specific snapshots apply. Unrelated feature streams and a later final-PR body cannot substitute. Automatic downstream propagation remains stable-only.
Non-latest target, 1.0.0 -> 1.4.0 with latest 2.0.0	The explicit target stays 1.4.0 with its immutable target-era source/docs/template. Starting from 2.0.0 instead stops as a downgrade, not an upgrade.
Ambiguous floating baseline	A consumer's package 9.0.0 and today's v1 -> 1.8.0 alias do not identify the prior upstream. Retained run provenance for 1.4.2 can establish it; absent that evidence, Stage 1 blocks and registers the gap.
Missing release or action evidence	An empty 1.3.0 record in a crossed range is not no-action evidence. A source-bound authoritative external changelog may establish equivalent facts without MSX formatting; otherwise affected work blocks.
Missing or inapplicable template	A moving template branch without immutable compatibility blocks adoption. A product without an applicable template records why and continues with release evidence and validation.
Producer/template sequencing	Verified immutable producer candidate and template commits can establish review readiness. Final wiring remains a linked delivery obligation; producer completion waits for actual published-source reconciliation and necessary template delivery. No native blocker is waived.
Default target ordering, already-current state, and target drift	Default latest stable follows producer version order and designated stable lineage, not API position or a late backport timestamp. Equal version/source records an already-current outcome; lower targets stop. A newer release does not silently retarget ongoing work, and changed inputs invalidate affected evidence.

The walkthrough exposed a wording ambiguity in default target discovery; the latest pushed commit makes version/lineage selection and stopping equal/lower ranges explicit. Relative links and targeted Markdown lint pass after that clarification.

Convergence was scoped to consumer, template, and downstream work. #143 still needs a concrete standard-to-artifact inventory and enforcement; #136 needs its separately owned Gallery updater delivery; #187 needs router/published-URL enforcement. Other hits concern unrelated navigation, language, or palette work. No additional issue is fully delivered by this diff, so only #203 is a closing reference. Standards/framework alignment and final automated-review evidence are maintained in #205. Required-check enforcement remains separately open as #166; no settings or other branches are changed.

[MariusStorhaug]

Current candidate 1d06ba96be7a8c564994154eeab4f4ad261c76ad has successful PR-triggered Build, Lint, Links, Test, and Cross-repository links checks: Docs run https://github.com/MSXOrg/docs/actions/runs/34034356045 and cross-repository run https://github.com/MSXOrg/docs/actions/runs/34034356046. Publish is correctly skipped for a pull request, so no publication is claimed. The working tree is clean and all five logical commits are pushed. The final Copilot round has been explicitly requested; its complete summary and threads still need reconciliation before closing the author-side review work. Rechecked #166 and effective main rules: required status-check enforcement is still absent. #196 is still open and untouched. The draft and disabled auto-merge preserve that boundary rather than treating green runs as enforced protection.

[MariusStorhaug]

Read the complete current-head Copilot review 5125374401, including both suppressed comments. It found four related contract gaps: artifact-only immutable identities were incorrectly forced to have Git SHAs; automatic update eligibility did not bind the adoption-evidence gate; equal/lower propagation targets still conflicted with unconditional PR creation; and post-merge completion needed an explicitly open owning issue. These are in-scope procedure/connected-flow corrections, not requests to implement automation or change governance. I am addressing them and extending the walkthroughs before requesting another full review. #205 stays draft with auto-merge disabled.