dotnet-arm64-migration

name	dotnet-arm64-migration
description	Migrate one or more .NET projects to run on ARM64 (Apple Silicon, Windows on ARM, Linux/Alpine arm64, cloud arm64 like AWS Graviton / Azure Ampere). Use when the user wants to add arm64 support, target ARM64, build/publish for an arm64 runtime identifier (win-arm64, linux-arm64, linux-musl-arm64, osx-arm64), fix x86/x64 assumptions, resolve missing arm64 native NuGet assets, guard x86 hardware intrinsics, or run on Graviton / Ampere / Apple Silicon. User-initiated — match the user's stated intent to move a codebase onto ARM64. Not for general framework or package version upgrades.
requires-extension	upgrade-dotnet
metadata	{"discovery":"scenario","importance":"medium","weight":6000,"traits":"(.NET|CSharp|VisualBasic|DotNetCore|DotNetFramework)","scenarioTraitsSet":[".NET"],"post-completion":{"suggest-actions":["generate-report"]}}

.NET ARM64 Migration Scenario

Make one or more .NET projects build, publish, and run correctly on an ARM64 runtime identifier (win-arm64, linux-arm64, linux-musl-arm64, osx-arm64), fixing the project-file, NuGet native-asset, source-code, and infrastructure surfaces that assume x86/x64.

Scenario Overview

Goal: Move the scoped project(s) onto ARM64 — correct RID/platform settings, resolve arm64-capable native package assets, guard x86-only hardware intrinsics, and surface the remaining awareness/concurrency findings — validated by a cross-compile Gate (and native run/test when the host itself is arm64).

This scenario is user-initiated. The user asks to target ARM64; act on the scope they name. Do not auto-migrate unrelated projects.

What this scenario proves and does not prove. Milestone A delivers detection, the mechanical fixes, and a cross-compile Gate that proves restore + native-asset resolution + IL compilation for the target RID. The Gate does not prove that native libraries load, that P/Invoke entry points resolve, or that concurrency behaves correctly on arm64 — those require execution on matching-RID hardware (native run, emulated Smoke, or CI). Always tell the user this boundary; never present a green Gate as arm64 correctness certification.

Language coverage. The project-file/RID (0001–0003), NuGet native-asset (0004/0005), and infrastructure (0010) surfaces are language-agnostic and apply to both C# and Visual Basic projects. The source-code rules (0006–0009 and the code portion of 0012) analyze C# only — Visual Basic projects do not receive architecture-sensitive source-code analysis (x86 intrinsics, native-interop, bitness, or concurrency hazards). For a VB project, manually review those hazards; the automated scan will not surface them.

Workflow Stages

Run these stages in order:

0. Pre-Initialization — Confirm scope + target RID(s); detect host OS+arch; run the .NET Framework → modern-.NET decision gate (and the < 4.8.1 viability hard-block) before assessment. Uses the scenario-initialization system skill.
1. Assessment — Detect the four ARM64 surfaces (project / NuGet / code / infra) into assessment.md (+ JSON). Tool: generate_arm64_migration_assessment.
2. Planning — Triage findings into auto-fixable / guided / flag-only; order the 0001↔0012 fixes; decide package bump-vs-replace. Produces the planning artifacts.
3. Execution — Apply the project-file, RID, package, and intrinsic-guard fixes; leave review/flag findings as annotated tasks. Uses the executor's core task-execution steps.
4. Validation — Host-adaptive ladder: cross-compile Gate always; native build/run/test when the host matches the target RID.

Pre-Initialization

This section is used by the scenario-initialization system skill. It defines the scenario-specific parameters for this scenario.

Parameters to Confirm

⛔ Step 1 — Scope. Determine the scope from the user's request and normalize it to a concrete set of projects:

• A single project → that project.
• Several projects → those projects.
• A folder → every project under it.
• A solution (.sln/.slnx) → its projects.
• The whole repo → all projects in the repo.

Use get_solution_path / get_projects_info to discover and confirm the project set. Pass the scope to the assessment tool as inputMode (solution | projects | folder) and paths (semicolon-delimited).

⛔ Step 2 — Target RID(s). Confirm the arm64 runtime identifier(s) to target, a subset of { win-arm64, linux-arm64, linux-musl-arm64, osx-arm64 }:

• If the user named a target (e.g. "Graviton" → linux-arm64, "Apple Silicon" → osx-arm64, "Windows on ARM" → win-arm64, "Alpine/musl" → linux-musl-arm64), use it.
• Otherwise do not guess — leave targetRids unset and let the tool infer per project from project type and current RIDs, then confirm the inferred set with the user.
• RIDs are always lowercase. A RID that does not match a project's OS family is rejected per project by the tool — never force a cross-OS RID onto a project.
• linux-musl-arm64 is never inferred; only target it when the user explicitly asks for musl/Alpine, because a glibc linux-arm64 native asset is not reliably loadable on musl.

⛔ Step 3 — .NET Framework decision gate (before assessment). Cheaply read each project's TFM. For any project targeting .NET Framework, surface the modernize-first recommendation as an explicit decision gate — do not proceed silently:

• (a) Accept modernization → hand off to the dotnet-version-upgrade scenario first. Because there is no automatic scenario-chaining primitive, how you re-enter ARM64 depends on the Flow Mode:
  • Guided Flow Mode — stop after the version upgrade completes and tell the user to re-invoke this ARM64 scenario. Do not silently auto-resume the ARM64 intent; leave the ARM64 migration for a fresh, user-initiated run so the modernization can be reviewed on its own.
  • Automatic Flow Mode — you may run dotnet-version-upgrade and then continue into this ARM64 scenario in the same pass, but only if you: (1) record it explicitly as a two-phase effort (Phase 1 = dotnet-version-upgrade, Phase 2 = dotnet-arm64-migration) in scenario-instructions.md and the run summary; and (2) re-run the ARM64 assessment against the modernized project before applying any arm64 fix — never carry findings over from a pre-modernization assessment (the TFM, RIDs, and project style all change during modernization).
• (b) Decline modernization → proceed with ARM64 on .NET Framework, but apply the < 4.8.1 viability hard-block first: arm64 is only supported on .NET Framework 4.8.1+. A project below 4.8.1 that declines modernization is stopped at the gate with a clear message ("ARM64 needs .NET Framework 4.8.1+ or modernization to .NET") rather than being given unbuildable arm64 fixes. Remove that project from scope.
• Mixed solution (some Framework, some modern): apply the gate per Framework project. Modern projects proceed straight to assessment unaffected.

⛔ Step 4 — Exclusions. Collect any projects removed from scope at this gate (e.g. a < 4.8.1 project that declined modernization). Pass them to the assessment tool as excludedProjects (semicolon-delimited), or downgrade a solution/folder scope to inputMode=projects with only the surviving paths — so the tool never assesses a blocked project.

Step 5 — Proceed with the confirmed scope, target RID(s), and exclusions, passing them to initialize_scenario and then to the assessment stage.

Stage Instructions

⛔ IMPORTANT: Load each stage's instructions file only when entering that stage (not all upfront).

Stage 1: Assessment

When entering this stage, load: assessment.md

Runs generate_arm64_migration_assessment over the confirmed scope, detecting the four ARM64 surfaces (project-file settings, NuGet native assets, source-code hazards, infra) and writing assessment.md (+ JSON).

Stage 2: Planning

When entering this stage, load: planning.md

Triages each finding into auto-fixable / guided / flag-only, correlates Arm64.0001 with Arm64.0012 to decide the ordered platform-target fix, and chooses bump-vs-replace for native packages. Produces plan.md and scenario-instructions.md in the canonical format.

Stage 3: Execution

When entering this stage, load: execution.md

Applies the mechanical fixes (project-file, RID, safe package bumps, intrinsic guards) and leaves review/flag findings as annotated tasks, validating with builds. Uses the executor's core task-execution steps.

Stage 4: Validation

When entering this stage, load: validation.md

Runs the host-adaptive validation ladder: the cross-compile Gate always, plus native build/run/test when the host OS+arch (and libc flavor for musl) matches the target RID.

Success Criteria

• Every scoped project declares an arm64 RID for its target OS with correct lowercase casing.
• PlatformTarget=x86 / Prefer32Bit=true removed where safe, or handled as a guided task when 32-bit interop (Arm64.0012) is present.
• NuGet packages with native assets are at an arm64-capable version (safe bump) or the guided replacement/major-bump decision is recorded.
• Unguarded System.Runtime.Intrinsics.X86 uses have an …IsSupported guard + fallback.
• Awareness (0007/0008) and concurrency (0009) findings are surfaced as review tasks.
• The cross-compile Gate (build + publish for the target RID) passes for every scoped project — and the user is reminded this proves packaging/compile, not runtime correctness.
• Native run/test passed when the host matched the target RID; otherwise real-hardware / CI validation was recommended.

Error Handling

Framework project below 4.8.1 declines modernization (Pre-Init):

1. Stop that project at the gate — do not emit arm64 fixes it cannot build.
2. State the two viable paths: upgrade to .NET Framework 4.8.1+, or modernize to .NET via dotnet-version-upgrade. Exclude the project from scope and continue with the rest.

Target RID does not match a project's OS family:

1. The tool rejects it per project with a message — surface that to the user.
2. Confirm the correct RID for that project's OS, or exclude the project.

Arm64.0004 reports no safe arm64 version (only a major bump / TFM raise / replacement):

1. Do not auto-apply — present the guided options from the assessment.
2. Let the user choose: accept the major bump, raise the TFM first, or replace the package.

Cross-compile Gate fails:

1. Report the unresolved packaging / native-asset / compile issue — do not mark the migration complete.
2. Common causes: a package still missing an arm64 native asset (Arm64.0004), or an unresolved x86 assumption. Return to Execution for that finding.