`project upgrade`: Report the customization work an upgrade requires

[lasomethingsomething]

Problem statement

The upgrade wizard MVP #1167 takes a project from one Shopware version to another: readiness checks, target selection, Composer resolution as the real gate, guided execution, and a report. It stops where the customization work starts.

This epic covers the second half. After the version bump resolves, the developer still has to fix templates, themes, and custom code. Today the CLI knows some of this and shows none of it at the moment it is needed.

The problem: the wizard ends before the expensive part

An agency partner reviewing the wizard said the real work begins after the upgrade: storefront, themes, custom plugins. And that the Composer and plugin-check part is something an experienced developer can already do alone.

The upgrade report supports this. The dependency change is small. What follows is 361 files of code work, then eleven stabilization commits after the merge, including a Storefront block reference that was wrong and did not fail any build.

Three specific gaps:

• A template override pointing at a removed block, or a theme using a removed SCSS variable, produces no error. It stops working. Developers find these by loading pages.
• The upgrade wizard provides a final report confirming success. It does not say what is left, who owns it, or which parts tooling can handle.
• Findings exist only as terminal text, so CI jobs, vendors, support staff, and AI agents cannot work from the same facts.

Scope

Four stories:

Story	What it adds
Storefront overrides with no target	Reports overrides whose core template or block no longer exists
Theme customizations broken by the target version	Reports removed theme.json keys and removed core SCSS symbols
Wizard ends with a work queue	Panel 6 shows remaining work grouped by owner, instead of a success screen
Machine-readable findings file	findings.json next to the existing report, for CI, vendors, and agents

The first two produce findings. The last two deliver them.

Shared requirements

Every story in this epic must:

• Report only what it can verify against vendor/ on disk. Offline, no network.
• Never guess a replacement. A wrong guess breaks a shop silently, which is worse than saying nothing.
• Label every finding with owner and fixability, using the fields from Validation findings say who has to fix them #1309.
• Use the ok / needs review / blocked vocabulary already defined in Implement local Shopware upgrade wizard flow #1167, and the field names agreed with Deploy output available for logging deployment-helper#93.
• State what was not checked, so a short result is never read as a clean bill of health.
• Work in the non-interactive path, matching the -n parity the MVP already has.

Boundary: report, do not rewrite

This epic detects. It does not migrate code.

Rewriting Administration JavaScript and SCSS would mean maintaining per-version mapping tables permanently, and Core already ships admin:code-mods. Generating new code is covered by #1255, #1280, and #1297, where there is no existing code to be wrong about.

Detection reads what is on disk. It has no ongoing per-version maintenance cost. That is the difference.

Business / user impact

Developers estimating an upgrade currently work from release notes and experience. They discover the real cost after the version bump, when rollback is most expensive.

This epic moves that discovery earlier and makes it specific: which files, who fixes them, which parts are automated. Merchants benefit through their developers, in shorter upgrade projects and estimates that hold.

Proposed solution

No response

Who benefits?

No response

Out of scope

• Fixing anything automatically. This epic reports.
• Administration JavaScript and SCSS codemods.
• CMS element migration to the new component system. Not statically determinable today.
• Template block-content drift hashing and baselines. Revisit after the cheap override check proves useful.
• Functional or visual testing after the upgrade.
• Deploy-time log noise. That is Deploy output available for logging deployment-helper#93.

Acceptance criteria

• The linked stories cover Storefront override checks, theme checks, the post-upgrade work queue, and the machine-readable findings file.
• Every story follows the shared requirements above.
• At least 70% of completed major-version upgrade runs produce a non-empty work queue grouped by owner.
• Re-interview the agencies who said the wizard's value was unclear. At least 2 of 3 say the final panel tells them something they would otherwise have spent time finding.
• Findings render identically in the interactive wizard and the non-interactive path.

Readiness checklist

• Acceptance criteria are clearly defined.
• Backward compatibility impact addressed.
• Developer docs written.
• Tests added or adjusted accordingly.