PSA/docs/plans/2026-06-10-ticket-close-rules-design.md

# Ticket Close Rules — Design

- **Status:** Approved design
- **Created:** 2026-06-10
- **Branch:** `feature/ticket-close-rules`

## 1. Problem statement

Today nothing governs how a ticket gets closed. Any status update that lands on
a status with `is_closed = true` closes the ticket — no required resolution,
no time-entry check, no completion checklist — and abandoned tickets sit in
"Waiting for Customer" forever unless a human remembers them. The only
closure-adjacent checks in the codebase are idempotency guards in the workflow
`tickets.close` action (`shared/workflow/runtime/actions/businessOperations/tickets.ts`)
and a config constraint that a closed status cannot be a board default
(`packages/reference-data/src/actions/status-actions/statusActions.ts`).

This feature adds three capabilities, all configured per board:

1. **Pre-close validation gates** — conditions a ticket must satisfy before a
   human can move it to a closed status, with a permissioned override.
2. **Ticket checklists** — first-class checklist items on tickets (ad-hoc,
   template-applied, rule-applied, or workflow-applied), where checking an item
   permanently records and displays who checked it and when. Required-item
   completion is one of the close gates.
3. **Auto-close rules** — tickets sitting in a configured status with no
   activity for N days close automatically, with an optional warning
   notification beforehand.

## 2. Decisions (with rationale)

| Decision | Choice |
|---|---|
| Rule scope | Per board, matching how statuses, SLAs, and email settings are board-scoped |
| Gate behavior | Hard block with a permissioned override (`ticket.close_override`); overrides audit-logged with the failure list |
| Gate types (v1) | Resolution comment, ≥1 time entry, required checklist items complete, no open bundled children, admin-chosen required fields |
| Enforcement coverage | All human paths: MSP UI single + bulk, REST API. Exempt: workflow `tickets.close`, CSV import, auto-close engine, **and the client portal** (customers cannot satisfy internal-hygiene gates like time entry; blocking them dead-ends the conversation). Exempt closures are audit-logged as bypasses |
| Checklist accountability | `completed_by` + `completed_at` stored permanently and displayed inline (name + timestamp); check/uncheck written to the ticket audit log. No confirmation friction at click time |
| Checklist sources | Ad-hoc per ticket, reusable admin templates, auto-apply matchers (board/category/subcategory/priority), and a workflow action |
| Auto-close model | Status + inactivity timer per board, optional warning M days before close |
| Auto-close engine | Single recurring scan job (15 min) via the `IJobRunner` abstraction (`server/src/lib/jobs/JobRunnerFactory.ts`) — Temporal on EE/appliance/on-prem, pg-boss otherwise. A per-ticket Temporal workflow was considered and rejected: CE would still need the scan (two implementations), inactivity resets would require signal plumbing across every comment/reply path (the SLA Temporal workflow already needed a self-healing poll for exactly this drift), and config changes would invalidate in-flight timers. Day-granularity timers gain nothing from event-driven precision. `ticket_auto_close_state` is engine-agnostic, so the engine can be swapped later without a data-model change |

## 3. Data model

All tables tenant-scoped with composite `(tenant, id)` primary keys per the
Citus conventions (`server/migrations/20250804000001_fix_primary_keys_for_citus.cjs`).

**`board_close_rules`** — one row per board: `require_resolution_comment`,
`require_time_entry`, `require_checklist_complete`,
`require_no_open_children` (booleans), `required_fields` (jsonb array from an
allowed set: category, subcategory, priority, assignee, …), `is_enabled`.
A fixed v1 gate set means toggles, not a generic rule-row model.

**`ticket_checklist_items`** — live checklist on a ticket: `item_name`,
`description`, `order_number`, `assigned_to`, `is_required` (default true; only
required items gate closure), `completed`, `completed_by`, `completed_at`,
provenance (`source`: `manual` | `template` | `workflow`; nullable
`template_id`). Modeled after `task_checklist_items`
(`server/migrations/20241009225600_create_task_checklist_items.cjs`) plus the
accountability and provenance fields that table lacks.

**`checklist_templates`** / **`checklist_template_items`** — admin-defined
templates; items carry name/description/order/`is_required`. Items are
**copied** onto tickets, never referenced, so later template edits do not
mutate history.

**`checklist_template_apply_rules`** — `template_id` + nullable `board_id` /
`category_id` / `subcategory_id` / `priority_id` (null = match any). Evaluated
on ticket creation and on board/category change; application is additive and
idempotent — a template never applies twice to the same ticket.

**`board_auto_close_rules`** — multiple rows per board: `trigger_status_id`,
`inactivity_days`, nullable `warning_days_before`, `close_to_status_id` (must
be an `is_closed` status), `is_enabled`.

**`ticket_auto_close_state`** — engine scratchpad per ticket: matched
`rule_id`, `scheduled_close_at`, `warning_sent_at`. Recomputed/cleared whenever
activity resets the timer; prevents duplicate warnings and drives the
"will auto-close on …" banner.

**Permission:** `ticket.close_override` added to the RBAC seeds, granted to
Admin by default.

## 4. Enforcement flow

A single shared function in `packages/tickets`:

```ts
validateTicketClosure(trx, tenant, ticketId, user, options)
  → { allowed, failures: [{ rule, message, meta }], overridden? }
```

It loads the board's `board_close_rules` row and evaluates each enabled gate
inside the caller's transaction. Gate checks are cheap queries: resolution
comment → a comment tagged as resolution exists; time entry → any
`time_entries` row for the ticket; checklist → no incomplete `is_required`
items; open children → no open tickets bundled under this master; required
fields → null checks on the ticket row.

**Call sites** are the four places that already detect the open→closed status
flip:

- `updateTicket` — `packages/tickets/src/actions/ticketActions.ts`
- `updateTicketInTransaction` — `packages/tickets/src/actions/optimizedTicketActions.ts`
  (covers board view, bulk actions, move-to-board, TicketDetails)
- `TicketService.update` — `server/src/lib/api/services/TicketService.ts` (REST v1, mobile)
- client portal `updateTicketStatus` —
  `packages/client-portal/src/actions/client-portal-actions/client-tickets.ts`
  (exempt from gates, but instrumented for the closure-recording fix below)

On failure the chokepoint throws a typed `TicketCloseValidationError` carrying
the failures array — rendered as a blocked-close dialog in the UI and a 422
with structured details from the API. Bulk close validates per ticket and
reports per-ticket results instead of failing the batch.

**Override:** a request with `overrideCloseRules: true` is honored only when
the server confirms `ticket.close_override`; the override and its failure list
are written to `ticket_audit_logs` as `TICKET_CLOSE_RULES_OVERRIDDEN`.

**Exemptions** (workflow `tickets.close`, CSV import, auto-close engine,
client portal) pass a system bypass flag and are audit-logged as bypassed.

**Portal closure-recording fix (in scope):** the portal status-update path
currently neither sets `is_closed` / `closed_at` / `closed_by` nor publishes
`TICKET_CLOSED`. As part of wiring the chokepoint through it, it gains the same
closure side effects as every other path.

## 5. Auto-close engine

One recurring job, `auto-close-tickets`, every 15 minutes, registered through
`IJobRunner.scheduleRecurringJob`. Each run, per tenant:

1. **Match.** Find open tickets whose current status has an enabled
   `board_auto_close_rules` row. Compute `last_activity_at` (latest of
   comments, status changes, customer replies) and
   `scheduled_close_at = last_activity_at + inactivity_days`. Upsert
   `ticket_auto_close_state`; newer activity recomputes the row, resetting the
   timer and cancelling any pending warning/close.
2. **Warn.** Where `warning_days_before` is set and
   `now ≥ scheduled_close_at − warning`, send the new
   `ticket-auto-close-warning` notification template to the ticket contact
   (respecting tenant notification settings) and stamp `warning_sent_at`.
3. **Close.** Where `now ≥ scheduled_close_at`, close via
   `updateTicketInTransaction` with a system actor, the bypass flag, and an
   automatic comment ("Closed automatically after N days of inactivity").
   Riding the normal path means `TICKET_CLOSED`, closure emails, SLA resolution
   recording, surveys, webhooks, and search reindexing all fire exactly as a
   manual close would.

The close step re-validates inactivity inside the closing transaction, so
activity racing the scan cannot cause a wrongful close, and re-runs are
idempotent. The job is per-tenant, per-ticket try/catch — one bad ticket never
stalls the sweep.

## 6. UI surfaces

- **Board settings → Close Rules:** gate toggles, required-fields
  multi-select, and the board's auto-close rules list (trigger status,
  inactivity days, warning lead time, target closed status).
- **Settings → Checklist Templates:** template CRUD, drag-ordered items with
  per-item `is_required`, and each template's auto-apply matchers.
- **Ticket details — Checklist section:** checkboxes, inline add, "Apply
  template" picker. A checked item permanently shows the checker's avatar/name
  and timestamp inline. A progress chip ("3 of 5 required done") sits near the
  status control. Unchecking is allowed but clears who/when and writes an
  audit entry recording the uncheck and the prior signoff.
- **Blocked-close dialog:** lists each unmet condition with a quick action
  (jump to checklist, add time, …). Holders of `ticket.close_override` get
  "Close anyway" with an optional reason.
- **Auto-close banner:** "Will close automatically on <date> unless there's
  new activity", driven by `ticket_auto_close_state`.

## 7. Workflow integration

- New workflow action: apply a checklist template to a ticket.
- The existing `tickets.close` action keeps its bypass but logs it.

## 8. Testing

- **Unit:** each gate in `validateTicketClosure` (pass/fail/override paths).
- **Integration** (repo integration-test patterns): blocked/allowed/override
  closes across all four entry paths; accountability field writes on
  check/uncheck; template auto-apply on create and on board/category change;
  scan match/warn/close behavior with synthetic timestamps; portal
  closure-recording fix publishes `TICKET_CLOSED`.
- **Playwright:** blocked-close dialog flow; checklist who/when display;
  board settings and template settings CRUD.