Post 4 walked through upgrade.md as it exists today: a clean-git-state precondition, explicit version detection, order-dependent report application, and a build-clean bar for calling an upgrade finished. It’s already the most safety-conscious of the four spfx-dev-skills reference files — which is exactly why the proposals in this post lean toward closing the remaining risk gaps rather than introducing caution where there wasn’t any before.

As with post 3, none of what follows is a criticism, and none of it is announced by the maintainers. These are our own proposals, each with a runnable command, that we plan to test against real upgrade scenarios before considering a pull request to SharePoint/spfx-dev-skills.

Proposal 1: An Explicit Rollback Path

upgrade.md requires a clean git state before starting — but it never says what to do if the upgrade doesn’t go cleanly. If the report’s steps are applied, deprecated APIs are fixed, and npm run build still won’t pass after reasonable troubleshooting, there’s no stated next move. The project is left in a half-upgraded state with no explicit instruction to stop.

Proposed addition:

git reset --hard <pre-upgrade-commit-hash>

Or, for a lighter revert that keeps the working directory but discards changes:

git checkout .

Paired with a one-line rule: if the build still fails after applying all report steps and fixing obviously-related errors, roll back to the pre-upgrade commit and re-plan — rather than continuing to patch forward indefinitely.

Why this helps an agent specifically: the clean-git-state precondition from post 4 already makes this rollback completely safe — nothing is lost by reverting. What’s missing is permission to use it. An agent without an explicit “give up cleanly” instruction will often keep trying incremental fixes well past the point where a human would have just reverted and reconsidered the approach.

Proposal 2: Incremental Versions for Large Jumps

--toVersion <version> treats a one-minor-version bump and a four-major-version leap identically — one command, one report, one attempt. In practice, the further apart the current and target versions are, the more likely the report is to touch overlapping files in ways that are hard to reason about as a single diff.

Proposed addition:

m365 spfx project upgrade --toVersion <next-intermediate-version> --output md
# apply, verify, commit
m365 spfx project upgrade --toVersion <next-intermediate-version> --output md
# apply, verify, commit
# ...repeat until reaching the final target version

With a decision rule: when the version gap spans multiple major versions, upgrade through intermediate versions one at a time, verifying and committing after each, rather than jumping directly to the final target.

Why this helps an agent specifically: every intermediate step produces a small, reviewable diff and a known-good commit to roll back to if the next step goes wrong — turning one large, risky operation into several small, recoverable ones.

Proposal 3: Run the Existing Test Suite, Not Just the Build

upgrade.md‘s Verify step currently means: install dependencies, run npm run build, fix errors, and don’t call it done until the build is clean. A clean build proves the code compiles. It says nothing about whether the code still behaves the way it did before the upgrade.

Proposed addition:

npm test

(or npm run test, matching whatever script the project defines) — run as part of Verify, immediately after the build passes, with the same standard applied: new test failures introduced by the upgrade are treated as upgrade work still in progress, not a separate follow-up ticket.

Why this helps an agent specifically: an upgrade that changes a deprecated API’s default behavior (not just its signature) can compile perfectly cleanly while silently changing what the code does. A test suite is the only thing in this workflow positioned to catch that.

Proposal 4: Machine-Readable Output for Agent-Driven Diffing

upgrade.md only shows --output md — a Markdown report meant for a human to read top to bottom. That’s the right default for the final human review step post 4 ends on, but it’s a poor format for an agent trying to programmatically confirm “did I actually apply every step this report listed.”

Proposed addition:

m365 spfx project upgrade --toVersion <version> --output json

Used specifically for the “apply the report” step, where an agent can parse structured entries instead of pattern-matching against Markdown headings and bullet points — then switch back to the human-facing --output md report for the final review step, matching post 4’s existing “review the git diff before committing” instruction.

Why this helps an agent specifically: string-matching a Markdown report to verify completeness is fragile — formatting changes between CLI versions, or an unusual report structure, can cause an agent to silently miss a step. Structured JSON removes that entire class of failure.

Testing Before Proposing

All four proposals here get tested against real upgrade scenarios on our end before anything goes into SharePoint/spfx-dev-skills‘s CONTRIBUTING.md process — a clean single-minor bump, a multi-major jump, a project with customized files that need careful merging, and a project with an existing test suite. That PR is separate from this series, and we’ll link it here once it exists.

Next in the series: post 6 moves from procedural discipline to design discipline — react-design.md, the skill pack’s 16-section “Copilot UI Contract” for Fluent UI v9.

Source note: The baseline described in this post — what upgrade.md currently covers — is drawn from SharePoint/spfx-dev-skills, specifically plugins/spfx/skills/spfx/references/upgrade.md, and detailed in full in post 4. Every proposal in this post is our own, not sourced from the repo, and is marked as such throughout.