Documentation: Added upgrade and migration playbook for contract depl…

[Adediwura-dev]

Closes #587

📋 Description

Add a dedicated Contract Upgrade & Migration playbook and register it in the docs. This is a documentation-only change that standardizes pre-upgrade checks, step-by-step soroban commands for install/pause/upgrade/unpause, rollback options, and post-upgrade verification.

Files changed:

• CONTRACT_UPGRADE_PLAYBOOK.md (new)
• README.md (index entry)
• CONTRACTS_ARCHITECTURE.md (cross-reference)

🔗 Type of Change

• 🐛 Bug fix (non-breaking change that fixes an issue)
• ✨ New feature (non-breaking change that adds functionality)
• ⚠️ Breaking change (fix or feature that would cause existing functionality to change)
• 📚 Documentation update
• 🔒 Security improvement

---

🔒 SECURITY REVIEW (⭐ MANDATORY FOR SMART CONTRACT CHANGES)

Note: This PR is documentation-only. No smart contract or runtime code was modified.

Required: Security Checklist Sign-Off

• I have reviewed this PR against the Internal Security Checklist (SECURITY_CHECKLIST.md)

  N/A — documentation-only PR. No smart contract code was modified.
  

Slither Static Analysis Results

• Ran Slither locally: slither . --config-file slither.config.json

  N/A — documentation-only PR; no contract code changed.
  

• GitHub Actions Slither workflow passed:

  N/A — documentation-only PR; no contract code changed.
  

Handling Security Findings

• Option A: Fixed in This PR ✅

  N/A
  

• Option B: False Positive 🟡

  N/A
  

• Option C: Accepted Risk ⚠️

  N/A
  

---

📝 Testing

Functional Testing

• Unit tests added/updated for changes

  N/A — no runtime code changed; unit tests not required for docs-only PR.
  

• Integration tests passing

  N/A — no runtime code changed.
  

• Manual testing completed and documented below:

  - Verified `docs/runbooks/CONTRACT_UPGRADE_PLAYBOOK.md` exists and contains Prerequisites, Pre-Upgrade Checks, Migration & Upgrade Steps, Rollback Strategy, and Post-Upgrade Verification.
  - Confirmed `docs/runbooks/README.md` includes the new runbook entry and link.
  - Confirmed `docs/CONTRACTS_ARCHITECTURE.md` references the new playbook.
  - Performed quick repo checks:
    - `grep -n 'CONTRACT_UPGRADE_PLAYBOOK' docs -R`
    - `git show HEAD:docs/runbooks/CONTRACT_UPGRADE_PLAYBOOK.md | sed -n '1,120p'`
  - Pushed branch `migration_playbook` to remote for PR creation.
  

Security Testing

• Reentrancy test (if applicable) — N/A
• Access control test — N/A
• Boundary test — N/A

Test Coverage

• All new code paths have test coverage

  N/A — documentation-only PR.
  

• Security-critical paths have comprehensive test cases

  N/A — documentation-only PR.
  

• Coverage report: N/A — documentation only, no executable code added

---

🚀 Deployment Notes

No runtime deployment required. This PR adds a Markdown file and updates two existing Markdown files only.

Mainnet Readiness

• This code is ready for production deployment
• All critical tests pass (not applicable — docs only)
• Security review approved
• No temporary debug code
• No TODO comments

Breaking Changes

• Migration guide provided (not applicable)
• Deprecation period defined (not applicable)

---

📊 Automated Scan Results

• Slither Analysis: N/A — no contract code changed

✅ Reviewer Checklist

• PR author completed security checklist ✓
• All findings documented and categorized (fixed/false positive/excluded) — N/A
• Inline security comments are clear and justified — N/A
• Tests cover security-critical code paths — N/A
• No external calls bypass return value checks — N/A
• Access control is properly enforced — N/A
• State updates follow CEI pattern — N/A
• Input validation is comprehensive — N/A
• Follow-up actions (if any) tracked in issues

---

📞 Questions or Issues?

• For questions about the playbook content or to request an enhancement (e.g., add staging run checklist), comment on this PR or tag @security-team for guidance.

---

📋 Pre-Submit Checklist

• Description is clear and concise
• All security checklist items checked (✅ or explanation provided)
• All tests passing locally: npm test / existing CI unaffected — documentation-only change
• Linter passing: npm run lint — docs-only; lint unaffected
• Slither passing locally OR findings documented — N/A
• Code follows project style guide
• No merge conflicts
• Commits are clean and well-documented
• Branch is up-to-date with main