Incident Management v2: Breaking release, documentation and production hardening

[Aidaho12]

Parent epic: #45

Architectural direction

This issue follows the approved Incident Management v2 separation:

Alert -> AlertGroup -> Incident

• AlertGroup owns technical deduplication, source status, routing, notifications and escalation.

• Incident owns operational lifecycle, priority, commander, responders, stakeholders, affected services, root cause, resolution and ITSM references.

• Current technical behavior moves from /api/incidents to /api/alert-groups.

• /api/incidents is replaced directly and exposes only first-class Incidents.

• No /api/managed-incidents, compatibility alias or intermediate API is introduced.

• Manual AlertGroup creation explicitly creates an AlertGroup and initial child Alert.

• Manual Incident creation creates only a first-class Incident.

Architecture document: docs/architecture/incident-management-v2.md

Goal

Ship the AlertGroup/Incident separation as a safe, explicit breaking release with complete migration, documentation, security and operational quality.

Scope

• Commit the final Incident Management v2 architecture document.

• Write external API migration guide with endpoint, payload and identifier mapping.

• Provide database migration preflight, reconciliation report and rollback procedure.

• Update user, administrator, integration and troubleshooting documentation.

• Document On-call Roles, role-aware schedules, concurrent coverage and Incident-role mapping.

• Migrate existing schedules to Primary On-call with reconciliation and rollback coverage.

• Verify role-aware calendar, escalation targets and current-on-call API behavior.

• Document that On-call Roles are not RBAC roles and do not grant permissions.

• Document the separate Create Alert Group and Create Incident workflows, permissions and lifecycle effects.

• Complete permission matrix, backend isolation tests and secret-redaction tests.

• Verify audit and timeline coverage for every AlertGroup and Incident mutation.

• Add load, pagination, concurrency and idempotency tests for lists, timelines, links and transitions.

• Migrate notification-center references, internal URLs and actionable message links.

• Complete localization parity and accessibility review.

• Remove production ManagedIncident terminology and legacy /api/incidents AlertGroup assumptions.

• Publish breaking release notes requiring external API clients to migrate before upgrade.

Acceptance criteria

• A new installation contains the separated schema, explicit manual AlertGroup creation and first-class manual Incident creation.

• An upgraded installation preserves all supported operational data and produces a reconciliation report.

• Rollback is tested before new-model writes make rollback unsafe, with that boundary documented.

• OpenAPI and bundled UI contain no old /api/incidents AlertGroup contract.

• Security tests cover cross-team links, Incident mutations and external integration secrets.

• Performance limits and operational metrics are documented.

• All supported workflows are documented for operators and non-expert administrators.

• The release checklist blocks shipping until Incident Management v2: AlertGroup classification and review policy #46-Incident Management v2: Incident links, merge, split and duplicate handling #50 core separation is complete.

• Existing schedules upgrade to Primary On-call without changing who is on call.

• Role-aware schedules, calendar and escalation behavior are documented and regression-tested.

• The release checklist blocks shipping until Incident Management v2: On-call roles and role-aware scheduling #59 is complete.

Dependencies

• Incident Management v2: AlertGroup classification and review policy #46

• Incident Management v2: Incident domain model and legacy data migration #47

• Incident Management v2: Replace incident API with AlertGroup and Incident APIs #48

• Incident Management v2: Separate Alerts and Incidents UI #49

• Incident Management v2: Incident links, merge, split and duplicate handling #50

• Incident Management v2: Automation and Event Orchestration integration #51

• Incident Management v2: External references and generic ITSM framework #52

• Incident Management v2: Jira Service Management connector #53

• Incident Management v2: Incident and alert-quality analytics #54

• Incident Management v2: On-call roles and role-aware scheduling #59