docs: recommend against --strict in migrate documentation

[morgo]

The default idempotent restart behavior is safer and more convenient for most users. --strict was added for a specific internal use case and can cause unexpected failures when checkpoints become stale.

This updates the docs/migrate.md to:

• Add a prominent warning recommending against --strict
• Explain the specific failure scenarios where strict mode causes errors
• Clarify that the default behavior (clean up and restart) is usually correct

Fixes #736

[Copilot]

Pull request overview

Updates the migration documentation to discourage use of --strict and clarify how default restart behavior handles stale checkpoints, aligning guidance with the tool’s safer idempotent resume/restart approach.

Changes:

• Add a prominent warning that --strict is generally not recommended.
• Document concrete failure scenarios where strict mode exits instead of restarting.
• Clarify that the default behavior cleans up stale checkpoints and restarts, usually the desired outcome.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Kiran01bm]

Other places that needs updating ?

1. pkg/migration/resume-from-checkpoint.md -- recommends --strict with caveats:

   • Line 59: "Use --strict mode if losing progress silently is unacceptable."
   • Lines 62–71 ("Strict mode" section): describes --strict neutrally as a feature to enable, with no caveat that it is not recommended for general use.

2. pkg/migration/migration.go (line 44) — Kong CLI help string for the flag:

   Strict bool `name:"strict" help:"Exit on --alter mismatch when incomplete migration is detected" optional:"" default:"false"`

The help text does not mention that the flag is discouraged. Since spirit migrate --help is most users' first exposure to the flag, it should reflect the same "not recommended" framing as docs/migrate.md.