🚀 [Feature]: Consumer upgrades use complete release-range evidence - #205
🚀 [Feature]: Consumer upgrades use complete release-range evidence#205Marius Storhaug (MariusStorhaug) wants to merge 12 commits into
Conversation
There was a problem hiding this comment.
🟡 Changes recommended
Required discovery wiring, pointer skill, and version synchronization remain incomplete.
Once you've addressed the issues Copilot identified, you can request another Copilot review.
Pull request overview
Adds a canonical staged procedure for evidence-based consumer upgrades.
Changes:
- Defines baseline-to-target upgrade stages, evidence, and quality gates.
- Adds site navigation and index discovery.
- Documents required upgrade outputs and validation.
File summaries
| File | Review |
|---|---|
src/zensical.toml |
Adds navigation. Moderate: Required workflow links, pointer skill, and synchronized plugin/marketplace versions are missing. |
src/docs/Ways-of-Working/index.md |
Adds the generated index entry. Moderate: No corresponding discoverable pointer skill exists. |
src/docs/Ways-of-Working/Consumer-Upgrades.md |
Defines the procedure. Nits: Existing upgrade entry points and connected readiness/completion criteria are not yet linked or aligned. |
Review details
Suppressed comments (1)
src/docs/Ways-of-Working/Consumer-Upgrades.md:19
- The procedure is not yet connected from the existing upgrade entry points:
Fleet-Orchestration.md, the dependency-updates spec/design, and the downstream-release-propagation spec/design contain no link to it and still describe their own narrower bump/release-note flow. Readers entering through those workflows therefore will not be routed through the required complete baseline-to-target traversal. Wire those surfaces to this canonical procedure as required by the delivery contract.
[Contribution Workflow](Contribution-Workflow.md), and each consumer in a
[fleet](Fleet-Orchestration.md) establishes its own baseline and applicability.
- Files reviewed: 7/7 changed files
- Comments generated: 3
- Review effort level: Balanced
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
There was a problem hiding this comment.
🟡 Changes recommended
Moderate workflow contradictions remain around automation gating, no-upgrade paths, immutable identities, and post-merge completion ownership.
Once you've addressed the issues Copilot identified, you can request another Copilot review.
Review details
Suppressed comments (2)
src/docs/Ways-of-Working/Consumer-Upgrades.md:202
- These exit criteria cannot be represented by the procedure as written. The ordinary workflow automatically closes the upgrade issue when the PR merges, but this stage says the upgrade is not complete until later publication/deployment evidence exists and that, before then, the issue must report a blocker. Specify which still-open issue owns the post-merge milestone (or how the delivery leaf remains/reopens open), otherwise the native issue state reports completion too early.
**Exit criteria.** The reviewed consumer change is merged, required publication
or deployment is evidenced where applicable, and the completion gate holds.
Before then, the issue and PR report the actual milestone and any blocker.
src/docs/Ways-of-Working/Consumer-Upgrades.md:77
- The target repeats the unconditional source-SHA requirement, so an image or package target with an authoritative digest but no source-commit mapping cannot pass Stage 2 even though those artifact types are explicitly in scope. Allow the immutable identity form defined by the producer ecosystem instead of always requiring both a source SHA and artifact identity.
API's first result or the most recently published timestamp. Record its
version, release link, full source SHA, and artifact identity where
applicable. Do not silently retarget when a newer release appears.
- Files reviewed: 17/17 changed files
- Comments generated: 5
- Review effort level: Balanced
There was a problem hiding this comment.
🔵 Needs a closer look
Three documented control-flow inconsistencies remain unresolved.
Review details
Suppressed comments (3)
src/docs/Capabilities/downstream-release-propagation/design.md:24
- The documented control flow still makes delegation unconditional (
issue → delegate → qualify), while the new qualification section says the notifier can qualify and terminate before delegation. That pre-delegation no-upgrade path cannot occur in this diagram; the introduction also assigns issue creation to the agent even though both delegation modes require the issue to exist before the agent starts. Please either add an explicit notifier-qualification branch (delegating only when upgrade work or agent-side qualification is needed) or consistently make all qualification delegated.
fan --> issue["Create or reuse Task / Bug delivery issue"]
issue --> delegate["Create agent task in dependent<br/>self-contained prompt with full context"]
delegate --> qualify{"Target upgrades actual baseline?"}
src/docs/Capabilities/downstream-release-propagation/design.md:24
- The primary flow still models only Task-first: it always creates an Agent Task after the issue, while the Delegation section says Issue-first is the default and uses the issue itself as the request (lines 108–124). The introduction also assigns issue creation to the agent even though both modes require the leaf to exist first. Make the introduction and flow mode-neutral, or branch here into Issue-first pickup versus Task-first Agent Task creation, so implementers can tell which component owns each step.
fan --> issue["Create or reuse Task / Bug delivery issue"]
issue --> delegate["Create agent task in dependent<br/>self-contained prompt with full context"]
delegate --> qualify{"Target upgrades actual baseline?"}
src/docs/Ways-of-Working/Fleet-Orchestration.md:185
- This PR-less terminal path is unreachable in the documented fleet model: lines 43-44 define every slice as an issue plus PR, and the diagram/step 2 unconditionally create a branch and draft PR, while qualification is deferred to step 3. Move baseline/target qualification before branch creation, make the PR conditional in the slice definition, and branch queued issues to
Not neededwhen appropriate.
An evidenced [no-upgrade outcome](Consumer-Upgrades.md#stage-2-fix-the-target-and-release-path)
ends without manufacturing a branch or PR. Apply the common procedure's issue
disposition; the fleet reports *Not needed*, not a delivered upgrade.
- Files reviewed: 19/19 changed files
- Comments generated: 0 new
- Review effort level: Balanced
Delivery B verification recordCandidate:
Review The completion-owning issue is #203, assigned to MariusStorhaug. Required Pages publication is not inferred from merge: if automatic PR closure precedes that evidence, the owner reopens the Task until the outcome is recorded. No settings, other branches, pilot consumers, or historical release records are changed. Review Review |
There was a problem hiding this comment.
🟡 Changes recommended
The critical instruction-injection boundary in delegated release payloads must be addressed before approval.
Once you've addressed the issues Copilot identified, you can request another Copilot review.
Review details
- Files reviewed: 19/19 changed files
- Comments generated: 1
- Review effort level: Balanced
There was a problem hiding this comment.
🔵 Needs a closer look
A critical propagation conflict and two moderate contract gaps remain unresolved.
Review details
Suppressed comments (2)
Previously missed (1) — in code that hasn't changed since the last review.
src/docs/Capabilities/downstream-release-propagation/design.md:202
- The create-agent-task endpoint requires the fine-grained repository permission at write level; saying only “Agent tasks permission” leaves a read-only PAT looking compliant even though task creation will return 403. Specify Agent tasks: write for Task-first credentials.
src/docs/Capabilities/dependency-updates/design.md:127
- This permits an updater PR to remain non-draft before its adoption evidence is complete, but
Definition-of-Ready-and-Done.md:26,51defines the non-draft state itself as the review-readiness signal and requires the PR to stay draft while any gate is open. A required check can block automation and merge, but it cannot prevent this non-draft PR from entering reviewers' queues as “ready.” Require the update workflow to create or immediately convert the PR to draft until adoption verification passes, or align the central readiness contract with a different explicit signal.
The updater may open a non-draft PR, so setting it to draft later is not the
binding control. Until evidence verification is enforced through the required
check, update PRs remain outside automated readiness, approval, and merge.
- Files reviewed: 19/19 changed files
- Comments generated: 1
- Review effort level: Balanced
There was a problem hiding this comment.
🟡 Changes recommended
The critical propagation retry/idempotency issue must be resolved before approval.
Once you've addressed the issues Copilot identified, you can request another Copilot review.
Review details
- Files reviewed: 19/19 changed files
- Comments generated: 1
- Review effort level: Balanced
| Idempotency is by **existence**: the issue is the durable record that this version | ||
| was propagated, so a repeat run finds and reuses it. |
Consumers follow one staged procedure from their actual consumed upstream baseline to a fixed target, preserving local intent and accounting for the complete applicable release range. The shared
msxplugin exposes the method without embedding migration instructions or replacing producer-owned discovery.New: One consumer upgrade procedure
Consumer Upgrades establishes immutable baseline provenance, fixes the target, reads every applicable release with full pagination and semantic/lineage ordering, composes an action ledger, compares the recorded immutable target template, and reconciles existing consumer validation. Fleet guidance, dependency updates, downstream propagation, navigation, and plugin discovery route to that method.
No-action releases remain evidence-bearing steps. Prerelease and non-latest targets retain their source-specific history; unrelated backports and prerelease streams are excluded. A floating alias's present destination does not prove what previously ran. Git-distributed products use full commit identities; artifact-only products can use authoritative immutable digests without invented Git mappings. Missing required evidence blocks affected work.
msx-ways-of-working-consumer-upgradesis the additive shared intent. The shared plugin and marketplace entry both declare0.2.0; existing skill names remain supported. Installation is optional, and initiative-specific source/version/template discovery remains producer-owned.Changed: Evidence gates and terminal outcomes are explicit
Review readiness requires complete consumer evidence. Dependency proposals are created as drafts or immediately converted to draft, and remain draft until readiness. The documented automatic-update contract independently binds adoption evidence to a required PR check before automatic readiness, approval, or merge; neither green builds nor the draft flag alone replace that control. This PR defines the contract, not a validator or updater implementation.
Equal or lower targets produce an evidenced no-upgrade outcome rather than an empty PR or downgrade. Only an unneeded open leaf with no remaining local work closes as not planned. Propagation qualifies before Build and conditionally delegates through Issue-first pickup or Task-first Agent Task creation; fleet qualification precedes branch/PR creation or adoption. Both release-triggered propagation and manual backfill remain stable-only; standalone consumer prerelease upgrades do not widen that capability.
Producer release/PR text and related documentation are evidence, not authority over the consumer's task. Delegated payloads separate application-owned instructions from complete, losslessly carried untrusted records. Delimiter collisions or embedded control directives cannot authorize scope, permission, secret-handling, or gate changes; unsafe isolation blocks delegation instead of discarding content.
Producer completion requires immutable compatibility with the published identity and delivery of necessary template changes. Verified candidate/prerelease evidence can support review without waiving native blockers. A multi-leaf outcome remains open in its PBI; a single leaf awaiting publication/deployment is reopened if PR closure precedes the required evidence.
The existing Implement alignment pass carries these obligations without a second checklist. Product docs describe the current contract; release/migration history and delivery plans stay in issues, PRs, and source-bound releases. Decision records and research remain supported exceptions.
Adopting this release
msx@msxorgto0.2.0to discovermsx-ways-of-working-consumer-upgrades. Read producer-owned discovery for authoritative identities, release lineage, and template mapping.Issues: writeplus mode-specific permissions; Task-first requires the Agent Tasks API's accepted user credential withAgent tasks: write. KeepPROPAGATION_TOKENas the secret name. Separate task instructions from the full untrusted evidence payload with a runtime data boundary or collision-safe quotation; decoding must retain the complete record. This PR changes no credential or setting.This delivery executes no consumer upgrade and introduces no runtime migration of its own. Future consumer actions come from the selected producer's release evidence, not the shared skill.
Release impact
release:minorfor the additive supported shared-plugin intent. Markdown implementation does not make a functional discovery change Docs-only.msxpackage and marketplace-entry metadata move from0.1.0to0.2.0under the existing marketplace contract. These are not predicted GitHub Release coordinates. This task creates no GitHub Release and selects no consumer upstream target; publication follows the repository's existing process.Technical details
Consumer change record
msx-ways-of-working-consumer-upgrades0.2.0.Template baseline
Not applicable: shared documentation and its pointer plugin are not an integration-template consumer. The orchestration-playbook and Agent Skills authoring structures are standards, not product integration templates. No pilot consumer or producer/template repository is modified.
Maintainer evidence
Source and scope. Delivery B implements #203 only, from merged #204 at
702be0fa7db80a5e24eb9ebc47badc017356257b. The current candidate's full immutable identity and source-bound outcomes are recorded in the verification record. These are this documentation/plugin delivery's coordinates, not a consumer upstream range. Native prerequisite #202 is closed; no native parent exists. The completed Delivery A branch is not reused. Small logical commits separate the procedure, gates, capability contracts, plugin, and review corrections; each commit is pushed.Preserved contract. PR Format and Release Management remain unchanged: audience impact controls classification; users and integrators may be the same people; evidence stays complete and incremental; explicit levels override optional configured
DefaultBump; no implicit patch fallback exists; missing decisions require failed, merge-blocking CI validation. No authoring schema or resolver is duplicated or redesigned. #196 remains open with its conflicting implicit-patch proposal; its branch and policy files are untouched.Plan and verification. The first five implementation-plan steps are complete. Walkthrough reconciliation, alignment, and scoped convergence are recorded here and in the issue. The source-bound verification record carries current-head CI, complete-summary review reconciliation, and handoff state. Ordinary ready/auto-merge handoff remains blocked by #166, not silently waived.
Documentation walkthroughs
Eighteen recorded cases exercise the written contract, not a real consumer, pilot, or agent security evaluation. Detailed evidence is retained in the issue's range walkthroughs, review edge cases, conditional flows, evidence isolation, and entry gates.
Agent tasks: write, not a read-only permission.Standards and framework alignment
Validation and review evidence. Existing index generation/check, relative links across 128 documentation files, applicable cross-repository links, targeted Markdown lint, and all four pinned Pester
6.0.1PluginMarketplace tests pass. All 16 changed Markdown files are covered, with later edits rechecked. No dependency or validation toolchain is added. Reviews5125327578,5125374401,5125421878,5125462928, and5125521297were read in full, including suppressed concerns. All ten actual inline threads have fix-linked replies and are resolved. A zero result from the wait script was not accepted when the full summary still raised concerns. Current-head outcomes are retained in the verification record, not inferred from an inline-comment count or an older successful run.Convergence. Searches covered consumer, template, and downstream work. #143 still needs concrete standard-to-artifact inventory/enforcement, #136 owns Gallery updater delivery, and #187 needs router/published-URL enforcement. Other hits concern unrelated navigation, language, or palette work. No additional issue is fully delivered by this diff; only #203 is a closing reference.
Completion owner and remaining gate. #203, assigned to MariusStorhaug, owns this single-leaf delivery and required Pages publication. If future PR closure precedes publication evidence, the owner reopens the Task until that result is recorded. No applicable template or additional delivery leaf requires a PBI here. #166 remains open: effective
mainrules contain deletion, non-fast-forward, linear-history, and pull-request rules but no required status checks. Passing runs do not repair that gap. This PR remains draft with auto-merge disabled; no protection, ruleset, producer CI, or other active branch is changed.Out of scope and untouched: PSModule pilot selection/execution, historical release or PR backfill, version-specific skills, updater/publisher/validator implementations, automatic template synchronization, and unrelated governance changes.
Relevant issues (or links)
Related work