support_backend/specs/008-sla-escalation/spec.md

# Feature Specification: SLA and Escalation

**Feature Branch**: `008-sla-escalation`

**Created**: 2026-09-03

**Status**: Draft

**Input**: User description: "Phase 8 of docs/10-implementation-roadmap.md: SLA policy engine,
business calendar/holiday support, durable pause/resume via BullMQ, rule-driven escalation
engine, escalation event audit. Per docs/05-orchestration-sla-escalation.md §5-6 and
docs/06-database-schema.md 'Domain: SLA' / 'Domain: Escalation'."

## User Scenarios & Testing *(mandatory)*

### User Story 1 - An admin defines SLA policies as configuration (Priority: P1)

An administrator defines an SLA policy — first-response/investigation/resolution/customer-
response time limits — optionally scoped to a product, category, problem type, and/or priority,
and tied to a business calendar. Nothing about SLA thresholds is hardcoded anywhere in the
system.

**Why this priority**: Every later capability in this feature reads a policy that has to exist
first.

**Independent Test**: Create an SLA policy with a resolution limit; confirm it's retrievable and
its fields are stored exactly as given.

**Acceptance Scenarios**:

1. **Given** an admin creates an SLA policy with a resolution time limit, **When** it's saved,
   **Then** it's retrievable with every field exactly as given, `active: true` by default.
2. **Given** a policy scoped to a product/category/problem type/priority, **When** two policies
   could both apply to the same ticket, **Then** the more specific one is preferred — same
   most-specific-match convention this system already uses for confidence policy (005) and
   capability scope (006).
3. **Given** an admin creates a business calendar with working hours and holidays, **When** it's
   referenced by a policy, **Then** due-date calculations for tickets under that policy use it.

---

### User Story 2 - An SLA run starts automatically when a ticket is assigned, with calendar-aware due dates (Priority: P1)

When orchestration (007) assigns a ticket, an SLA run starts for it automatically, with due dates
computed against the applicable policy's business calendar — never a naive `createdAt + N hours`
that ignores weekends, holidays, or working hours.

**Why this priority**: Nothing else in this feature — breach detection, pause/resume, escalation
— has anything to act on until a real, calendar-correct due date exists.

**Independent Test**: Assign a ticket under a policy with a resolution limit and a calendar whose
working hours exclude a weekend; confirm the computed due date skips the excluded time rather
than counting straight through it.

**Acceptance Scenarios**:

1. **Given** a ticket is assigned (007), **When** an applicable SLA policy resolves for it (User
   Story 1's most-specific-match rule), **Then** an SLA run starts with a resolution due date
   computed against that policy's calendar.
2. **Given** no policy matches, **When** a ticket is assigned, **Then** no SLA run is created
   rather than applying an arbitrary default — this feature does not invent a policy that was
   never configured.
3. **Given** a calendar with defined working hours and a holiday, **When** a due date is
   computed, **Then** time outside working hours and on holidays is excluded from the countdown.

---

### User Story 3 - SLA pause and resume are durable, not in-memory (Priority: P1)

When a ticket's status indicates it's waiting on the customer, its SLA run pauses — the clock
stops counting against the agent. When it resumes, the clock continues from where it left off,
never from zero and never having kept counting while paused. This state survives a process
restart.

**Why this priority**: Constitution Principle VII names this exact scenario — an SLA that keeps
counting during a customer-caused delay, or that resets on a restart, actively misrepresents
whether a real commitment was honored.

**Independent Test**: Start an SLA run, pause it, wait, resume it; confirm the resulting due date
reflects the paused duration being excluded, not counted twice.

**Acceptance Scenarios**:

1. **Given** a running SLA, **When** the ticket transitions to a waiting-for-customer state,
   **Then** the run's status becomes `paused` and its due date stops approaching.
2. **Given** a paused SLA, **When** the ticket transitions back to in-progress, **Then** the run's
   status becomes `running` again and the remaining time is preserved from the pause point.
3. **Given** a paused or running SLA run, **When** the process restarts, **Then** its state is
   unchanged on restart — pause/resume state is never held only in memory.

---

### User Story 4 - A breach is detected durably, never silently missed (Priority: P2)

When a running SLA's due date passes without the corresponding milestone happening, the run is
marked breached — detected by a durable background job, not a timer that only fires if the
process happens to still be running at the right moment.

**Why this priority**: Depends on User Stories 2-3 (a real due date, correctly paused/resumed)
existing first. A breach that's never detected is worse than no SLA at all — it's a false sense
of a commitment being tracked.

**Independent Test**: Start an SLA run with a very short resolution limit; confirm it's marked
`breached` once the due date passes, even simulating the checking job running in a separate
process invocation from the one that started the run.

**Acceptance Scenarios**:

1. **Given** a running SLA run whose due date has passed, **When** the breach-detection job next
   runs, **Then** the run's status becomes `breached` and its `breachedAt` timestamp is recorded.
2. **Given** an SLA run that completes (its milestone actually happens) before its due date,
   **When** breach detection later runs, **Then** it is not marked breached — completion is
   checked against the actual event, not assumed from elapsed time alone.
3. **Given** a paused SLA run, **When** breach detection runs while it's paused, **Then** it is
   never marked breached — a paused clock cannot breach.

---

### User Story 5 - A breach automatically triggers rule-driven escalation (Priority: P2)

An administrator defines escalation rules — trigger condition, target support-hierarchy node, who
to notify. When an SLA breach (or another configured trigger) occurs, the matching rule fires
automatically: the ticket moves toward the rule's target node and orchestration (007)
re-assigns it there, and an escalation event is durably recorded. This is never a hardcoded
`if L1 then L2` — it's evaluated against configured rules.

**Why this priority**: Depends on User Story 4 (a real breach signal to trigger on). This is the
other half of "durable SLA enforcement actually matters" — detecting a breach that nobody acts on
isn't meaningfully different from not detecting it.

**Independent Test**: Configure an escalation rule for `resolution_breach` targeting a specific
hierarchy node; breach an SLA run; confirm an escalation event is recorded, the ticket is
re-assigned via 007 scoped to that specific node, and the rule's configured notification target
is recorded (not necessarily delivered — see Assumptions).

**Acceptance Scenarios**:

1. **Given** an active escalation rule for `resolution_breach` scoped to a target node, **When**
   a matching SLA run breaches, **Then** an `EscalationEvent` is recorded with the rule, the
   reason, and `triggeredBy: system`.
2. **Given** an escalation event fires, **When** it completes, **Then** 007's assignment engine
   re-runs scoped specifically to the rule's target node — not a fresh, unscoped resolution —
   and the ticket's assignment history (007) reflects the new assignment with `strategy` reused
   from whatever the target node itself configures.
3. **Given** no escalation rule matches a breach, **When** the breach is detected, **Then** the
   SLA run is still marked breached (User Story 4) — the absence of a matching rule doesn't
   suppress breach detection, it only means no automatic escalation follows.
4. **Given** multiple active rules could match the same trigger, **When** more than one does,
   **Then** every matching rule fires its own escalation event — this feature does not pick just
   one.

---

### User Story 6 - A human can manually trigger escalation, audited the same way (Priority: P3)

An agent or admin can explicitly escalate a ticket to a specific target node, for a stated
reason, without waiting for an automatic trigger — recorded through the same `EscalationEvent`
audit trail as an automatic one.

**Why this priority**: Depends on User Story 5's event/re-assignment mechanism already existing.
Automatic triggers won't cover every real reason to escalate (doc 05 §10 names several this
feature doesn't compute automatically — see Assumptions); a human needs an explicit path that
still produces the same durable record.

**Independent Test**: Manually escalate a ticket to a named target node with a reason; confirm an
`EscalationEvent` with `triggeredBy` set to the calling actor is recorded and the ticket is
re-assigned via 007 to that node.

**Acceptance Scenarios**:

1. **Given** an admin manually escalates a ticket to a target node, **When** it completes,
   **Then** an `EscalationEvent` is recorded with `triggeredBy` set to the actor (never
   `system`), and 007 re-assigns the ticket scoped to that node.
2. **Given** a manual escalation targets a node that doesn't exist, **When** it's attempted,
   **Then** it's rejected — never a dangling escalation event pointing nowhere.

---

### Edge Cases

- What happens if a ticket has no assigned agent yet when its SLA would otherwise start? An SLA
  run only starts on a successful assignment (User Story 2) — an unassigned ticket (007's "no
  eligible agent" outcome) has no SLA run to track, consistent with there being no one yet to
  hold to a commitment.
- What happens if a business calendar has no working hours configured at all for a given day?
  That day contributes zero time toward any due-date countdown — an unconfigured day is never
  silently treated as 24 available hours.
- What happens if an SLA policy's calendar is deleted or unreferenced after runs already exist
  against it? Out of scope — this feature does not implement calendar deletion, only creation and
  the `active` state every other configuration entity in this system already uses.
- What happens when a ticket is reopened after being resolved, with a completed SLA run already
  on record? Out of scope for this feature to define a new run automatically — reopening (a
  future problem-resolution-phase concept) may need its own SLA-run-restart decision; this
  feature's SLA runs are 1:1 with a ticket's first, straightforward assignment→resolution
  lifecycle.
- What happens if two escalation rules would move a ticket to the same target node at once (a
  race between an automatic breach and a simultaneous manual escalation)? Both `EscalationEvent`
  rows are recorded (never lost — durable audit is unconditional); 007's own re-assignment
  path already handles a ticket being assigned twice in quick succession correctly (it's the same
  version-row-per-period `Assignment` mechanism 007 already built and tested for concurrent
  writes), so no new concurrency mechanism is needed here.

## Requirements *(mandatory)*

### Functional Requirements

- **FR-001**: The system MUST let an admin create an SLA policy with first-response/
  investigation/resolution/customer-response time limits, optionally scoped to product/category/
  problem type/priority, referencing a business calendar.
- **FR-002**: When multiple SLA policies could apply to the same ticket context, the system MUST
  prefer the most specific match — never an arbitrary or first-found selection.
- **FR-003**: The system MUST let an admin create a business calendar with working hours and
  holidays.
- **FR-004**: Due-date computation MUST exclude time outside a calendar's working hours and on
  its holidays — MUST NOT compute a due date as a naive elapsed-time addition that ignores the
  calendar.
- **FR-005**: An SLA run MUST start automatically when a ticket is successfully assigned (007),
  using the most-specific-matching policy (FR-002); when no policy matches, no run is created.
- **FR-006**: An SLA run's status MUST be one of `running`, `paused`, `warning`, `breached`, or
  `completed`, matching doc 06's defined set.
- **FR-007**: When a ticket transitions to a waiting-for-customer state, its SLA run MUST pause;
  when it transitions back, the run MUST resume with its remaining time preserved — never reset
  to the full original duration and never having continued counting while paused.
- **FR-008**: SLA pause/resume state and due dates MUST be durable — recomputable and correct
  after a process restart, never dependent on an in-memory timer (Constitution Principle VII).
- **FR-009**: A running SLA run whose due date has passed MUST be detected and marked `breached`
  by a durable background job — never missed because the triggering process wasn't running at
  the exact due moment.
- **FR-010**: An SLA run that completes its milestone before its due date MUST NOT be marked
  breached, regardless of what a naive elapsed-time check alone would suggest.
- **FR-011**: A paused SLA run MUST NOT be marked breached while paused.
- **FR-012**: The system MUST let an admin create an escalation rule — trigger type, condition,
  target hierarchy node, and who to notify — scoped to a policy, matching doc 06's
  `EscalationRule` shape.
- **FR-013**: An SLA breach (FR-009) MUST be evaluated against every active escalation rule
  configured for `resolution_breach` (and, where applicable, the other SLA-derived trigger
  types this feature computes — see Assumptions); every matching rule MUST fire its own
  escalation event — never just the first match.
- **FR-014**: Firing an escalation rule MUST record a durable `EscalationEvent` (rule, reason,
  `triggeredBy`, timestamp) and MUST re-run 007's assignment engine scoped specifically to the
  rule's `targetNodeId` — never a fresh, unscoped resolution that could land elsewhere.
- **FR-015**: A breach with no matching escalation rule MUST still be recorded as breached
  (FR-009) — the absence of a rule never suppresses breach detection itself.
- **FR-016**: The system MUST let an admin or agent manually escalate a ticket to a specific,
  existing target node with a reason, recorded through the same `EscalationEvent` mechanism as an
  automatic escalation, with `triggeredBy` set to the calling actor.
- **FR-017**: A manual escalation targeting a nonexistent hierarchy node MUST be rejected.

### Key Entities

- **SLA Policy**: A configured set of time limits (first response/investigation/resolution/
  customer response) scoped to product/category/problem type/priority, referencing a business
  calendar — never a hardcoded threshold.
- **SLA Run**: The durable, per-ticket tracking of one policy's due dates and status against a
  real ticket, survivable across a process restart.
- **Business Calendar / Holiday**: Working hours and excluded dates a due-date calculation
  respects — the mechanism that keeps SLA math honest.
- **Escalation Policy / Rule**: Configured trigger conditions and target hierarchy nodes — never
  a hardcoded escalation ladder.
- **Escalation Event**: The durable, audited record of every escalation, automatic or manual,
  including which rule (if any) fired it and who/what triggered it.

## Success Criteria *(mandatory)*

### Measurable Outcomes

- **SC-001**: 100% of due-date calculations under a policy with a configured calendar exclude
  non-working time — verified against a calendar with at least one full excluded day.
- **SC-002**: 100% of SLA runs correctly reflect pause/resume across a simulated process restart
  — the paused duration is never double-counted and never dropped.
- **SC-003**: 100% of SLA runs whose due date has passed are marked `breached` within one
  breach-detection job cycle, even when the detecting process is a different invocation than the
  one that started the run.
- **SC-004**: 100% of SLA breaches with a matching active escalation rule produce both an
  `EscalationEvent` and a re-assignment scoped to the rule's target node.
- **SC-005**: 100% of manual escalations targeting a nonexistent node are rejected, never
  producing a dangling event.

## Assumptions

- **This feature does not build a notification-delivery mechanism** — an escalation rule's
  `notify` field (doc 06) is stored and returned as configured, but this feature does not send an
  email/Slack/webhook notification; `platform/notifications` (doc 07) remains an untouched module
  group, same convention as every prior feature leaving an adjacent, not-yet-built module alone.
- **Only `resolution_breach` and `first_response_breach` are wired to a real trigger signal in
  this feature** — doc 05 §6 lists ten trigger types; the other eight (inactivity, priority
  increase, customer escalation request, repeated reopen, manual [built as its own user story,
  User Story 6, not a rule trigger], product defect, dependency timeout, critical incident)
  require signals this codebase doesn't compute yet (idle-time tracking, reopen counting,
  explicit defect/incident flagging) — `EscalationRule.triggerType` accepts any of doc 06's
  values as configuration data, but only the two SLA-breach types are ever actually evaluated by
  this feature. This mirrors 006's `assignmentStrategy`/`slaPolicyId` fields being stored as real
  data before this feature gave them a real consumer.
- **Investigation SLA and customer-response SLA are stored as policy fields (FR-001) but this
  feature only computes/tracks the resolution and first-response due dates on `SLARun`** — doc 06's
  `SLARun` itself only models `firstResponseDueAt`/`resolutionDueAt` explicitly; investigation and
  customer-response timers would need their own due-date fields doc 06 doesn't define, which is a
  refinement left for whichever future phase actually needs to enforce them (matching this
  system's "refine the conceptual schema when a feature needs the refinement, not speculatively"
  convention).
- **SLA run creation happens once, on a ticket's first successful assignment** — reopening,
  multiple resolution cycles, and re-running an SLA clock for a reassigned-after-resolution
  ticket are out of scope (Edge Cases) — that's future problem-resolution-phase territory.
- **Breach detection runs on a durable, periodically-scheduled BullMQ job** (a repeatable job,
  not a per-run delayed job scheduled at creation time) — checking every active `running` run's
  due date against the current time on each tick, rather than scheduling one delayed job per SLA
  run. This is a deliberate simplicity/robustness tradeoff, not an aspiration to replace later —
  see research.md for the full reasoning.