source-migration-rewrite-apply-validate

name	source-migration-rewrite-apply-validate
description	Use when an agent needs to preview, select, apply, stage, compose, or validate MigrateToWinUI rewrite plans for Avalonia or WPF source migrations. Triggers on safe rewrites, rewritePlans, convert --dry-run, apply --rules, verify, compose --validate, report validation, rule-pack validation, and guarding source mutation.

Applying and Validating Rewrites

Use this skill whenever a task involves safe rewrite plans or file-changing migration operations. The default posture is preview first, apply narrowly, then verify. Stage or compose target output when the user wants a migrated project tree.

For repeated analyzer/code-fix rounds, prefer the deterministic wrapper:

python3 plugins/migrate-to-winui-agent/scripts/analyzer_codefix_workflow.py <input> --source <avalonia|wpf> --target both --mode preview --bundle
python3 plugins/migrate-to-winui-agent/scripts/analyzer_codefix_workflow.py <input> --source <avalonia|wpf> --target both --mode apply --rules <id> <id> --rounds 2 --bundle

Repo Entry Points

• CLI contract: specs/001-migration-core/contracts/cli.md
• Report schema: specs/001-migration-core/contracts/report.schema.json
• Rewrite models: src/MigrateToWinUI.Core/Diff
• Edit applicator: src/MigrateToWinUI.Core/TextEditApplicator.cs
• Staging/composition: src/MigrateToWinUI.Core/Staging
• Validation: src/MigrateToWinUI.Core/Validation
• Report writers: src/MigrateToWinUI.Core/Reporting
• Rule-pack schema: specs/001-migration-core/contracts/rule-pack.schema.json
• Built-in/default rule packs: rulepacks/avalonia-to-winui.v1.json, rulepacks/wpf-to-winui.v1.json

Rewrite Safety Model

• Safe: may be applied mechanically when generated from the current input, source framework, target, and rule-pack set.
• Review: diagnostic or edit needs human inspection before promotion; do not bulk-apply.
• Manual: target design required; never convert into a source edit without a new implementation and tests.

Rule-pack JSON files are diagnostic-only in this repo. They can add findings and rule specs, but they do not by themselves create safe automated rewrites.

Deterministic Workflow

1. Capture a baseline report.

   dotnet run --project src/MigrateToWinUI.Cli -- analyze <input> --source <avalonia|wpf> --target <winui3|uno|both> --format json --report artifacts/baseline-report.json
   

   Expected report fields include sourceFramework, target, inventory, files, findings, and rewritePlans.

2. List and explain candidate rules.

   dotnet run --project src/MigrateToWinUI.Cli -- rules list
   dotnet run --project src/MigrateToWinUI.Cli -- rules explain <AW2Uxxxx|WP2Uxxxx>
   dotnet run --project src/MigrateToWinUI.Cli -- rules catalog rulepacks --format json
   

   If rules catalog exits 2, fix invalid rule-pack files before trusting reports that depend on them. Redirect stdout to a file only after ensuring the output directory exists.

3. Preview exact edits.

   dotnet run --project src/MigrateToWinUI.Cli -- convert <input> --source <avalonia|wpf> --target <winui3|uno|both> --dry-run --rules <id> <id> --preview artifacts/rewrite-preview.txt --report artifacts/preview-report.json
   

   Check that:

   • Every applied rule id was requested or intentionally included.
   • Every edit comes from a Safe rewrite plan.
   • Manual-review findings remain in the report.
   • The preview was generated after the latest source changes.

4. Prefer staging or composition for migrated output.

   dotnet run --project src/MigrateToWinUI.Cli -- compose <input> --source <avalonia|wpf> --target <winui3|uno|both> --out artifacts/target-projects --project-name MigratedApp --clean --validate
   

   Expected output:

   • generated target shell project(s)
   • copied migrated source files
   • copied assets/resources when explicitly mapped
   • skipped manual-review rewrite plans
   • validation step statuses

5. Apply to source only after explicit approval.

   dotnet run --project src/MigrateToWinUI.Cli -- apply <input> --source <avalonia|wpf> --target <winui3|uno|both> --rules <id> <id>
   

   Expected output: Applied safe rewrites to N file(s).

6. Verify and report residual migration work.

   dotnet run --project src/MigrateToWinUI.Cli -- verify <input> --source <avalonia|wpf> --target <winui3|uno|both>
   dotnet run --project src/MigrateToWinUI.Cli -- detail <input> --source <avalonia|wpf> --target <winui3|uno|both> --format md --out artifacts/post-apply-dashboard.md
   

   verify should exit 0 when no error-level findings remain and 2 when verification or validation fails.

Source-Mutation Guardrails

• Never run apply as the first migration command.
• Never run apply with --source auto when the workspace has mixed or ambiguous Avalonia/WPF evidence.
• Never apply all rules to a broad repo unless the preview was reviewed and the target profile is known.
• Never manually edit source based only on a preview offset after files changed; regenerate the preview.
• Never remove manual-review findings from a report or dashboard because a safe rewrite was applied.
• Never use destructive git commands to back out a failed apply. Inspect git diff, then make targeted edits or ask the user.
• Keep generated/staged artifacts outside source input directories unless the user explicitly chose that layout.

Validation Commands

Use focused test filters for rewrite changes:

dotnet test --filter "FullyQualifiedName~RewriteDiffServiceTests|FullyQualifiedName~RewriteSelectionServiceTests|FullyQualifiedName~CSharpMigrationEngineTests|FullyQualifiedName~XamlMigrationEngineTests"
dotnet test --filter "FullyQualifiedName~StagedMigrationServiceTests|FullyQualifiedName~TargetProjectStagingServiceTests|FullyQualifiedName~ValidationRunnerTests"

Use sample fixtures for end-to-end confidence:

dotnet run --project src/MigrateToWinUI.Cli -- convert samples/AvaloniaInput --source avalonia --target both --dry-run --preview artifacts/avalonia-preview.txt
dotnet run --project src/MigrateToWinUI.Cli -- convert samples/WpfInput --source wpf --target both --dry-run --preview artifacts/wpf-preview.txt
dotnet run --project src/MigrateToWinUI.Cli -- verify samples/AvaloniaInput --source avalonia --target both
dotnet run --project src/MigrateToWinUI.Cli -- verify samples/WpfInput --source wpf --target both

Exit Codes

• 0: completed without error-level findings.
• 1: command usage, IO, bad image, or unknown rule failure.
• 2: verification or validation failures, error-level findings, or rule-pack catalog validation errors.
• 3: API coverage failed because scanned source APIs remain unclassified.

Delivery Checklist

When reporting results, include:

• Input path, source framework, and target profile used.
• Rule ids previewed or applied.
• Whether source files were mutated, staged, or only reported.
• Report, preview, dashboard, or composition artifact paths.
• Validation commands run and their exit codes.
• Remaining Review or Manual blockers by rule family.