Repository navigation
Define the evergreen consumer upgrade procedure and completion gates #203
Description
Activity
- added a commit that references this issue
on Sep 6, 2026 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.
Delivery B kickoff is isolated on
consumer-upgradesfrom remotemainat702be0fa7db80a5e24eb9ebc47badc017356257b; 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
mainrules 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.
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.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.The shared
msx-ways-of-working-consumer-upgradesskill 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 from0.1.0to0.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 intests/PluginMarketplace.Tests.ps1; no dependency or validation toolchain was added. Final walkthrough, alignment/convergence evidence, and complete Copilot review reconciliation remain before handoff.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.1The 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.0A required timeout -> timeoutSecondschange 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.0sequence is read after baseline1.0.0; an unrelated maintenance-line1.0.1is excluded with lineage evidence.A -> B -> Ccomposes toA -> Cwhen direct adoption is supported; reversed flag changes can net to no edit, but a required data conversion remains. No-action1.3.0is retained.Explicit prerelease, 2.0.0-rc.2 -> 2.0.0-rc.10Numeric 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.0with latest2.0.0The explicit target stays 1.4.0with its immutable target-era source/docs/template. Starting from2.0.0instead stops as a downgrade, not an upgrade.Ambiguous floating baseline A consumer's package 9.0.0and today'sv1 -> 1.8.0alias do not identify the prior upstream. Retained run provenance for1.4.2can establish it; absent that evidence, Stage 1 blocks and registers the gap.Missing release or action evidence An empty 1.3.0record 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.
Current candidate
1d06ba96be7a8c564994154eeab4f4ad261c76adhas 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.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.Review corrections are pushed in
01e69c7(ecosystem-authoritative immutable identities),504c056(binding required-check signal for automated adoption), and0bc427d(no-upgrade termination and an open post-merge completion owner). Added walkthroughs cover artifact-only digests without Git mappings, green builds with incomplete adoption evidence, equal/lower targets without empty PRs, and PBI versus single-leaf reopening for post-merge milestones. Existing unrelated PR work is never canceled from a version comparison alone. Navigation/index descriptions now reflect the no-upgrade outcome. The existing index/link checks, all 16 changed Markdown files, and all four pinned PluginMarketplace tests pass after these corrections; no validation or automation implementation was added.Completion ownership for this delivery: #203 remains the single completion-owning Task, assigned to MariusStorhaug. After a future merge, its required Pages publication is not inferred from PR closure; if the PR closes the Task before successful publication evidence exists, the named owner reopens it and keeps it open until that outcome is recorded. There is no applicable integration template or extra independently delivered leaf here, so no PBI or pilot work is created. #166 still prevents the ordinary ready/auto-merge handoff; this PR remains draft and unarmed.
The wait script returned zero for review
5125421878, but its full summary said Needs a closer look and contained three suppressed control-flow concerns. It was not accepted as clean. The correction makes propagation actor ownership and delegation mode-neutral, adds the notifier-side no-upgrade branch, and moves fleet qualification ahead of branch/PR creation. The diagrams and written paths now cover notifier termination, Issue-first pickup, Task-first Agent Task creation, unknown-provenance blocking, and new-versus-adopted fleet PRs. No actual inline thread exists for these suppressed concerns; their resolution is recorded here and in the PR evidence rather than fabricating a thread reply.Read the complete review
5125462928; its remaining concern is the instruction boundary around producer release payloads. The correction applies existing Security/Continuous Practices guidance: complete producer records remain lossless evidence, not governing agent instructions. Both delegation modes isolate that payload from application-owned task instructions with collision-safe quotation or a runtime data boundary; proposed adoption actions are validated through the common ledger, and an unsafe boundary blocks delegation instead of dropping content. A documented adversarial-record walkthrough covers embedded delimiters and attempted control overrides. This does not add a runtime implementation, alter release history, or claim an executed agent security evaluation.Read the complete review
5125521297, including its two suppressed concerns. The correction keeps both release-triggered propagation and manual backfill stable-only, rejecting a prerelease backfill before fan-out or issue creation. Standalone consumer prerelease upgrades remain supported outside that capability. Task-first credentials now explicitly requireAgent tasks: write. Dependency proposals are created as draft or immediately converted to draft and remain there until readiness, while the required adoption-evidence check independently prevents automated readiness/approval/merge; neither control substitutes for the other. The walkthroughs now cover both entry points and both draft/check signals. These remain documentation-only corrections; no workflow, credential, ruleset, or consumer is changed.Review
5125583484found that issue existence could mask failed agent engagement on retry. The spec/design now separate delivery identity, active execution, and terminal handoff: an issue-only retry resumes missing qualification/delegation; active work is reused; failed or uncertain engagement is reconciled without launching duplicates; and only a matching PR handoff or verified no-upgrade outcome permits a no-op. Discovery/creation and handoff attempts are serialized, correlation references stay on the GitHub issue, and Issue-first creation alone does not authorize pickup. The diagram and failure table use the same recovery path. This adds a documentation walkthrough for interrupted handoff, not an updater implementation or a new state store.
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
Merged contract and kickoff
Use a fresh session/worktree from
maincontaining MSXOrg/docs#204, merged as702be0fa7db80a5e24eb9ebc47badc017356257b. 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
DefaultBumpwith 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
src/docs/Ways-of-Working/Consumer-Upgrades.mdsrc/docs/Ways-of-Working/Definition-of-Ready-and-Done.mdsrc/docs/Ways-of-Working/Workflow-Stages/Implement.mdsrc/docs/Ways-of-Working/Documentation-Model.mdsrc/docs/Ways-of-Working/Fleet-Orchestration.mdsrc/docs/Capabilities/dependency-updates/{spec,design}.mdandsrc/docs/Capabilities/downstream-release-propagation/{spec,design}.mdsrc/docs/Capabilities/agentic-development/design-plugin-marketplaces.md.github/plugin/msx/skills/msx-ways-of-working-consumer-upgrades/SKILL.mdsrc/zensical.toml, generated indexes,.github/plugin/README.md, and applicable plugin discovery/manifestsUse 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
Consumer-Upgrades.mdand connect the existing readiness, completion, alignment, documentation-model, and fleet surfaces to its single procedure.tests/PluginMarketplace.Tests.ps1before adding the thin skill. Wire navigation/discovery, synchronize plugin/marketplace versions, and regenerate indexes with.github/scripts/Update-DocumentationIndex.ps1..github/scripts/Invoke-PesterSuite.ps1if its pinned dependency setup is needed; introduce no new validation toolchain.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.