Migrate Extjs4 To Extjs7

Migrate Ext JS 4 to Ext JS 7 (classic toolkit)

Core principle

One framework hop, no redesign. The application moves from Ext JS 4.x to Ext JS 7.x classic on a single cutover branch, keeping global Ext.app.Controller MVC, the classic theme, and every request and response the Java backend already sees. Architecture change, restyling, and API modernization are separate later projects.

Fixed decisions

Settled. Do not reopen them and do not quietly improve past them mid-slice. Recorded per project in the acceptance contract, assets/inventory-templates.md section 0 — which is also what the verification gate reads, so that neither skill has to load the other.

Source-structure policy

The framework changes. The application's shape does not.

Preserved by default: class names, namespaces, aliases, xtypes, folder layout, inheritance, controller ownership, refs, component selectors, event names, and public behavior. Modify the existing class locally whenever possible — the smallest edit inside the class that already owns the behavior.

Not introduced by default: replacement components, wrapper classes, compatibility abstractions, new base classes, shims, or duplicated implementations. Each adds a class the application did not have, and a migration that adds classes is no longer one anyone can review against the Ext 4 original.

The single exception is a confirmed 7.7.0 incompatibility that cannot be repaired safely inside the existing class — confirmed meaning verified against the target release, not inferred from an audit count or a mapping table. Fill in the exception record (assets/inventory-templates.md section 7) before writing the class. Absent that record, the smaller edit was not attempted.

The clean-scaffold option replaces generated infrastructure only — .sencha/, the generated app.json and bootstrap, theme scaffolding, build configuration. Application classes transplant as they are: do not reorganize, rename, or rewrite them on the way in. Restructuring requires separate user authorization and is its own project.

Phases

One shipped target, ordered so the work is diagnosable and the branch is never a mystery. Each phase names the reference carrying its detail; read that rather than working from recall.

Raising the visual bar to pixel comparison is separately authorized work, taken once the structural check passes across the matrix — not something a slice drifts into, and not something phase 4 closes by default.

When a phase-1 or phase-2 failure cannot be attributed to a particular major release, bucket the findings per version before planning the fix (upgrade-map.md §0a). Nothing intermediate ships.

Task modes

Verification

These are the criteria — what must be true for a slice to be done. The procedure for establishing them independently, and the PASS/FAIL/INCOMPLETE verdicts, belong to the verification gate, which works from the acceptance contract rather than from this file.

The screen matrix. A flat list of screens is not enough where menus are role-driven, the UI is localized, and mobile behavior differs. The unit of verification is:

role × entry point (menu item) × locale × desktop/mobile × read-only vs write workflow

Enumerate it in phase 0 and sample it deliberately, not accidentally: every role at least once, every locale at least once against a screen with formatted dates and numbers, mobile at least once against any screen with bespoke touch handling. Record which cells were covered and which were reasoned about but not exercised. Tables: assets/inventory-templates.md sections 1a and 1b.

Five gates, each evidence rather than opinion.

• Build — the project's own canonical build, on the profile the deployed shell really serves. Zero errors from phase 2 onward; the production profile before phase 4 closes.
• Runtime console — zero uncaught exceptions and zero unaccounted warnings. The threshold is accounted for, not zero, because deprecation output is expected on a 4-to-7 hop: unclassified warnings must be zero at every phase boundary, while classified, accepted ones may stay flat. A non-zero deprecation count does not fail completion. An unaccounted warning does.
• Browser workflow and structural visual check — the workflow users actually perform, at the visual threshold in Fixed decisions. Deferred parity is reported not assessed, never as compared and equivalent.
• HTTP contract — every request the screen makes, against the phase 0 capture, on every field assets/inventory-templates.md section 2 lists. Store proxies, tree loads, form submissions, standalone Ext.Ajax, uploads, downloads and print or export endpoints all count; payload JSON alone is not the contract.
• Server-side tests, where the hosting application has a suite. Nothing the backend receives should change, so its own tests are the cheapest evidence that nothing did — and the only automated evidence covering the writer changes, which carry the highest data-loss risk and raise nothing on the client. Run after any slice touching a reader, writer, proxy or id format; where no suite exists, say so rather than letting the client-side gates imply that ground is covered.

Report INCOMPLETE rather than passing when the baseline is missing, a matrix cell cannot be reached, or evidence was not actually collected. A workflow that cannot be automated — gated on a hardware token, a browser plugin, an external service — is verified manually and recorded as manually verified, never silently skipped.

Resources

Non-negotiable safeguards

• Do not treat an audit count as a defect count, or convert an occurrence count into a bulk edit. One search term routinely spans several mapping statuses — root: alone covers a removed reader config, a working writer alias and an unchanged tree config; margins: also matches defaultMargins:, which is a different fix. Counts include commented-out code. Split by status, verify the receiver, read the hits.
• Do not convert MVC to MVVM. No ViewController, no ViewModel, no bind as an architectural change. Use a scope-resolution config only where the framework requires one to resolve a string reference, and say so in a comment.
• Do not change what the server sees. Payload shape, parameter names, phantom id format and response handling stay identical unless the backend changes in the same slice with tests.
• Do not delete what you cannot explain. For an override, plugin or workaround: establish what framework behavior it modified and whether Ext 7 still behaves that way, then decide. For the vendored SDK or anything under it: extract the application code embedded in it and account for every classpath entry pointing into it first. Hand-appended translations inside a vendored locale file, and stock third-party classes relocated into the SDK so the build resolves them, are both the common case, both excluded from the source scan, and both load-bearing.
• Do not silence detection. Globally disabling ARIA validation, suppressing deprecation output, or turning off bufferedRenderer app-wide to avoid fixing row heights all hide work rather than doing it. Accepting an inventoried deprecation is the opposite: the warning keeps printing and the debt is written down.
• Do not replace a deprecated-but-present API to tidy up. Verify its status on 7.7.0 and leave it, recorded as debt, unless it malfunctions, reaches into removed or private internals, affects security or a server contract, or the user asked for modernization.
• Do not weaken or skip tests, accept new screenshot baselines, or relax assertions to make a slice pass. The visual threshold is the one exception, and only because it was lowered deliberately and in writing for the whole migration, with what it defers recorded — the opposite of a slice quietly relaxing a bar to get through.
• Preserve unrelated changes in dirty worktrees.

Handoff

State the target Ext and Cmd versions in use, the phase reached, the screens migrated and verified, the verification evidence collected per screen, the overrides retained and why, the compatibility-layer status, remaining deprecation warnings, known visual differences, and the rollback method.