PSA/ee/docs/plans/2026-02-21-contract-auto-renewal-and-renewals-queue/PRD.md

PRD — Contract Auto-Renewal and Renewals Queue

• Slug: contract-auto-renewal-and-renewals-queue
• Date: 2026-02-21
• Status: Draft

Summary

Add first-class contract renewal management to Billing Contracts: renewal settings during contract setup, a dedicated actionable Renewals queue, and due-date automation that can create internal tickets. The system must support fixed-term and evergreen contracts, tenant defaults with optional per-contract override, and runtime compatibility for both on-prem (pg-boss) and hosted/EE (Temporal) automation execution.

Problem

MSPs currently rely on end_date awareness and ad-hoc process to decide whether to renew or terminate contracts. This creates avoidable revenue leakage, missed non-renewal notices, and inconsistent ownership of renewal decisions.

Current contract surfaces support start/end dates and expiration reporting, but they do not support:

• explicit renewal behavior on each contract assignment,
• a single operational queue for upcoming renewal decisions,
• standardized queue actions (renewing, non-renewing, create draft, snooze),
• configurable due-date automation (ticket creation) with assignment defaults.

Goals

1. Capture renewal intent and notice-window behavior at contract creation/edit time.
2. Compute and surface a single operational date (decision_due_date) for renewal work.
3. Provide an actionable Renewals queue with 90-day triage buckets and owner/status workflows.
4. Support tenant-level defaults with optional per-contract override.
5. Automatically create internal renewal tickets at due date when configured.
6. Support fixed-term contracts and evergreen annual-review flow in the same queue model.
7. Ship as one cohesive release spanning wizard, queue, actions, and automation.

Non-goals

1. Sending customer-facing renewal quote emails from queue actions.
2. New billing/invoice pricing engines for renewal uplift or pro forma quoting.
3. Full CLM/legal document lifecycle features.
4. Replacing existing contract status model (draft, active, terminated, expired) in this release.
5. New feature-flag infrastructure or rollout orchestration beyond normal release controls.

Users and Primary Flows

• Billing manager / account manager:
  • sets renewal behavior during contract creation/edit,
  • reviews upcoming decisions in queue,
  • marks contracts renewing or non-renewing,
  • snoozes decisions with explicit date.
• Service manager / coordinator:
  • owns assigned renewal tasks,
  • works queue by due-date buckets,
  • opens renewal draft contracts from queue.

Primary flows:

1. Create fixed-term contract with end date, choose renewal behavior and notice period.
2. Create evergreen contract (no end date) with annual-review configuration.
3. Review queue by 0-30, 31-60, 61-90 decision windows.
4. Mark renewing and auto-create next-term draft contract.
5. Mark non-renewing and close renewal work item.
6. Snooze and assign renewal work item.
7. Due-date automation creates internal ticket when configured.

UX / UI Notes

1. Contract Basics step (ContractWizard) gets a conditional Renewal Settings card:

• if end_date exists: fixed-term renewal settings.
• if end_date absent: evergreen annual review settings.

2. Billing gets a new top-level Renewals tab/page:

• queue table with filters + action menu,
• default horizon 90 days,
• bucket presets and owner filters.

3. Client Contracts tab gets an Upcoming Renewals summary widget:

• count by 0-30 / 31-60 / 61-90,
• quick entry into Renewals queue.

4. Queue actions in v1:

• Mark renewing (auto-create renewal draft and open editor),
• Mark non-renewing,
• Create renewal draft,
• Snooze.

5. Queue primary sort key is decision_due_date (not raw contract end date).

Requirements

Functional Requirements

FR1 — Contract Setup and Renewal Configuration

1. Capture renewal settings on client contract assignments in the contract wizard and edit flows.
2. Support renewal modes: none, manual, auto.
3. If fixed-term (end_date set), capture notice period and renewal term behavior.
4. If evergreen (end_date null), capture annual-review cadence and notice period.
5. Validate incompatible states in UI and server (e.g., auto-renew with missing term strategy when required).

FR2 — Tenant Defaults and Contract-Level Overrides

1. Add tenant defaults for renewal behavior and due-date automation target.
2. Support per-contract override toggle (use tenant defaults vs explicit override values).
3. Preserve deterministic fallback behavior when override values are partially unset.

FR3 — Renewal Decision Date Engine

1. Compute decision_due_date for each active client contract.
2. Fixed-term formula: decision_due_date = end_date - notice_period_days.
3. Evergreen formula: derive next anniversary window and subtract notice period days.
4. Recompute decision dates when contract dates/settings change.
5. Prevent duplicate active work items for the same contract renewal cycle.

FR4 — Renewals Queue and Dashboard Entry Points

1. Add Renewals Billing tab and queue page.
2. Add Upcoming Renewals widget in Client Contracts tab.
3. Queue must support filters: horizon, bucket, owner, status, renewal mode, fixed/evergreen.
4. Queue must show due-date centric columns and actions.

FR5 — Queue Actions and Renewal Workflow

1. Add queue statuses: pending, renewing, non_renewing, snoozed, completed.
2. Implement action transitions with actor + timestamp + optional note.
3. Mark renewing must auto-create draft renewal contract (per chosen product decision).
4. Create renewal draft must be available as explicit independent action.
5. Snooze must require a future target date.

FR6 — Automation and Ticket Creation

1. At decision_due_date, create/update queue work item if unresolved.
2. When tenant/contract policy says create internal ticket, create one ticket idempotently.
3. Store linkage from renewal work item to created ticket.
4. Ticket defaults (board/status/priority/assignee) must come from renewal automation settings.

FR7 — Evergreen Annual Review Flow

1. Include evergreen contracts in queue using annual review cycle date.
2. Support the same status/actions as fixed-term contracts.
3. After a cycle is completed, prepare next evergreen cycle work item.

FR8 — Reporting and Existing Surface Alignment

1. Align existing contract expiration reporting with renewal decision model.
2. Preserve existing expiration semantics while adding decision-due visibility.
3. Avoid regressions in existing Contract Expiration Report consumers.

FR9 — Runtime Compatibility (On-prem PG Boss vs Hosted/EE Temporal)

1. Renewal automation job path must support on-prem pg-boss runtime.
2. Renewal automation job path must support hosted/EE Temporal runtime.
3. Ensure behavior parity regardless of runtime (idempotency, ticket creation, retry semantics).
4. Respect existing runtime selection and fallback patterns (JobRunnerFactory).

FR10 — Permissions, Security, and Auditability

1. Restrict queue mutations to authorized billing users.
2. Ensure tenant isolation in all queue queries and actions.
3. Record auditable state transitions and key actor metadata.

Non-functional Requirements

1. Queue list queries for default 90-day horizon should complete within existing Billing table UX expectations.
2. Renewal work-item creation and ticket automation must be idempotent across retries.
3. Runtime-independent behavior parity must be verified between pg-boss and Temporal paths.
4. All date handling must use existing date-only conventions for contract dates to avoid timezone drift.

Data / API / Integrations

Data model additions

1. client_contracts additions (assignment-level settings):

• renewal_mode (none|manual|auto)
• notice_period_days (int)
• renewal_term_months (nullable int)
• use_tenant_renewal_defaults (bool)
• evergreen cycle metadata (as needed for annual review computation)

2. default_billing_settings additions (tenant defaults):

• default renewal mode
• default notice period
• due-date action policy (queue_only or create_ticket)
• default ticket routing fields (board/status/priority/assignee)

3. New queue table (recommended): client_contract_renewal_work_items:

• work item identity + tenant + client_contract_id
• decision_due_date, cycle_start, cycle_end
• status, assigned_to, snoozed_until
• created_ticket_id, created_draft_contract_id
• last_action, last_action_by, last_action_at, note/reason fields

API / action surfaces

1. Extend ClientContractWizardSubmission and related actions to include renewal settings.
2. New renewal queue actions:

• list/query queue
• mark renewing
• mark non-renewing
• create renewal draft
• snooze
• assign owner

3. Integrate with existing ticket creation action path (tickets.create) for automation side effects.

Integrations

• Billing dashboard/tab composition.
• Contract wizard basics step.
• Existing event bus + workflow runtime event model.
• On-prem scheduled jobs via pg-boss.
• Hosted/EE automation via Temporal.

Security / Permissions

1. Read queue: billing read permission.
2. Mutate queue actions: billing update permission.
3. Tenant defaults changes: billing settings update permission.
4. Ticket automation execution: system/service actor with tenant-scoped permission enforcement.

Observability

No net-new observability framework is required for v1. Reuse existing audit/event patterns and existing job/runtime failure reporting surfaces. Track enough state in renewal work items to diagnose retries and failures without adding a separate telemetry subsystem.

Rollout / Migration

1. Add schema migrations for new contract renewal columns, default settings fields, and queue table.
2. Backfill existing active fixed-term contracts with deterministic defaults (manual, default notice period, tenant default usage).
3. Do not auto-create queue/tickets for historical expired/terminated contracts.
4. Stage rollout sequence:

• deploy schema + read-compatible code,
• deploy write paths and queue UI,
• enable scheduled automation processing.

Open Questions

1. Should renewal automation ticket defaults be separate from inbound-ticket defaults, or reuse them where unspecified?
2. What is the canonical evergreen anniversary anchor for contracts with manually edited start dates over time?
3. Do we require a hard block against activating renewal drafts until the original contract is marked renewing/non-renewing, or allow parallel status transitions?

Acceptance Criteria (Definition of Done)

1. Contract wizard supports fixed-term and evergreen renewal settings and persists them per client contract assignment.
2. Billing has a functional Renewals queue tab with 90-day buckets and required actions.
3. Client Contracts includes upcoming-renewals summary widget linked to queue.
4. Mark renewing auto-creates and links a renewal draft contract.
5. Due-date automation creates at most one ticket per renewal cycle when policy is enabled.
6. On-prem (pg-boss) and hosted/EE (Temporal) execute equivalent renewal automation behavior.
7. Existing contract expiration report remains functional and reflects decision-date semantics where applicable.
8. Features/tests checklists are populated and traceable to this PRD.