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

PRD: Ticket Close Rules

• Status: Draft (scope approved via design review)
• Owner: Robert Isaacs
• Created: 2026-06-10
• Design doc: docs/plans/2026-06-10-ticket-close-rules-design.md
• Branch: feature/ticket-close-rules

1. Problem statement & user value

Nothing governs how a ticket gets closed today. Any status update landing on a status with is_closed = true closes the ticket — no required resolution, no time-entry check, no completion checklist — and tickets abandoned in "Waiting for Customer" sit open forever unless a human remembers them. MSPs lose billing (closed tickets with no time logged), lose accountability (no record of who verified completion steps), and carry stale open-ticket noise.

This feature gives boards three new capabilities:

1. Pre-close validation gates — per-board conditions a ticket must satisfy before a human can close it, hard-blocked with a permissioned override.
2. Ticket checklists — first-class checklist items on tickets (ad-hoc, template, auto-applied, or workflow-applied) where checking an item permanently records and conspicuously 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 advance warning to the customer.

2. Goals

• Per-board close gates: resolution comment, ≥1 time entry, required checklist items complete, no open bundled children, admin-chosen required fields.
• Hard block with structured failure reporting in UI (dialog) and API (422); override via new ticket:close_override permission, audit-logged.
• Checklists with permanent completed_by/completed_at accountability, template management UI, auto-apply matchers, and a workflow action.
• Auto-close via a single recurring scan job on the existing IJobRunner abstraction (Temporal on EE/appliance/on-prem, pg-boss otherwise).
• Auto-close rides the normal close path so emails, SLA recording, surveys, webhooks, and search reindexing fire exactly as for a manual close.
• Fix the client portal closure-recording gap (is_closed/closed_at/ closed_by + TICKET_CLOSED publication) as part of wiring.

3. Non-goals

• No reopen rules (who may reopen, reopen windows) — future work.
• No per-rule block-vs-warn configuration; all enabled gates hard-block.
• No attestation ceremony (typed initials/notes) on checklist check-off.
• No generic transition-policy engine; gates are ticket-closure-specific.
• No per-ticket Temporal workflow engine for auto-close (see design §2 for the rejection rationale); the scan is the single engine for all editions.
• No REST API endpoints for checklist CRUD in v1 (UI uses server actions); the API surface is limited to close-validation behavior on existing ticket update endpoints.
• No backfill of accountability fields onto project task checklists.
• Client portal users are exempt from close gates (they cannot satisfy internal-hygiene conditions); portal closures are audit-logged as such.

4. Users & primary flows

• Technician: sees a checklist on the ticket with a progress chip near the status control; checks items (name + timestamp recorded inline); attempts to close; if gates fail, a dialog lists each unmet condition with a quick action (jump to checklist, add time).
• Dispatcher/Manager (with ticket:close_override): same dialog plus "Close anyway" with optional reason; override and failure list land in the ticket audit log.
• Admin: configures gates and auto-close rules per board in board settings; manages checklist templates and their auto-apply matchers in a new Ticketing settings tab.
• Customer (portal): can still close/resolve their own tickets unimpeded; receives an optional warning email before auto-close; replying resets the inactivity timer and cancels the pending close.
• Automation: workflows can apply a checklist template to a ticket; workflow tickets.close, CSV import, and the auto-close engine bypass gates with the bypass audit-logged.

5. Functional requirements

5.1 Close validation gates

• One board_close_rules row per board: require_resolution_comment, require_time_entry, require_checklist_complete, require_no_open_children, required_fields (jsonb array from the allowed set: category, subcategory, priority, assignee), is_enabled.
• Shared chokepoint validateTicketClosure(trx, tenant, ticketId, user, opts) in packages/tickets, evaluated inside the caller's transaction at the exact open→closed flip detection points in: updateTicket (ticketActions.ts), updateTicketInTransaction (optimizedTicketActions.ts), TicketService.update (REST v1).
• Gate queries: resolution comment → comments.is_resolution = true or metadata->>'closes_ticket' = 'true'; time entry → any time_entries row with work_item_id = ticket_id AND work_item_type = 'ticket'; checklist → no incomplete is_required items in ticket_checklist_items; children → no tickets rows with master_ticket_id = ticket_id AND closed_at IS NULL; required fields → null checks on the ticket row.
• Failure → typed TicketCloseValidationError with failures: [{ rule, message, meta }]; UI renders the blocked-close dialog, API returns 422 with structured details via the existing ValidationError pattern.
• overrideCloseRules: true honored only when the server confirms ticket:close_override; writes TICKET_CLOSE_RULES_OVERRIDDEN (with the failure list and optional reason) to ticket_audit_logs.
• Bulk close validates per ticket and reports per-ticket results.
• Bypass flag for workflow tickets.close, CSV import, auto-close engine, and client portal; bypassed closures audit-logged.

5.2 Ticket checklists

• ticket_checklist_items: name, description, order, assignee, is_required (default true), completed, completed_by, completed_at, provenance (source: manual | template | workflow; nullable template_id).
• Check sets completed_by/completed_at permanently displayed inline; uncheck clears them and writes an audit entry recording the prior signoff.
• Templates (checklist_templates + checklist_template_items) are copied onto tickets, never referenced; later template edits do not mutate history.
• Auto-apply matchers (checklist_template_apply_rules): nullable board / category / subcategory / priority (null = any), evaluated on ticket creation and on board/category change; additive and idempotent (a template never applies twice to one ticket).
• New workflow action tickets.apply_checklist registered in registerTicketActions() (shared/workflow/runtime/actions/businessOperations/tickets.ts).

5.3 Auto-close rules

• board_auto_close_rules (multiple per board): trigger_status_id, inactivity_days, nullable warning_days_before, close_to_status_id (must be is_closed), is_enabled.
• Recurring job auto-close-tickets every 15 minutes via IJobRunner.scheduleRecurringJob, registered in registerAllHandlers.ts / initializeScheduledJobs.ts following the reconcile-bucket-usage model.
• Per run: (1) match eligible tickets, compute last_activity_at (latest of comments, status changes, customer replies) and upsert ticket_auto_close_state (rule_id, scheduled_close_at, warning_sent_at) — newer activity recomputes and resets; (2) send ticket-auto-close-warning notification when inside the warning window, stamp warning_sent_at; (3) close due tickets via updateTicketInTransaction with system actor, bypass flag, and an automatic comment, re-validating inactivity inside the closing transaction.
• Per-tenant, per-ticket try/catch; idempotent re-runs.
• closed_by is null for auto-closed tickets; audit entry uses actor_type: 'system', source: 'system'.

6. Data model

Six new tables (all tenant-scoped, composite (tenant, id) PKs per Citus conventions, with RLS policies): board_close_rules, ticket_checklist_items, checklist_templates, checklist_template_items, checklist_template_apply_rules, board_auto_close_rules, ticket_auto_close_state. Full column detail in design doc §3.

New permission row: resource ticket, action close_override, granted to Admin by default. New notification subtype + system email template ticket-auto-close-warning.

7. UI / UX notes

• Board settings (BoardsSettings.tsx dialog): "Close Rules" bordered section (following the inbound-reply-reopen section pattern) with gate toggles + required-fields multi-select; "Auto-Close Rules" list editor (trigger status, inactivity days, warning lead, target closed status).
• Ticketing settings: new checklist-templates sub-tab in TicketingSettings.tsx (TICKETING_TAB_IDS) hosting ChecklistTemplatesSettings — template CRUD, item ordering via the existing up/down button pattern, per-item is_required, apply-rule matchers editor.
• Ticket details: new TicketChecklistSection.tsx composed into TicketDetails.tsx like sibling sections; checked items show checker avatar/name + timestamp inline; progress chip ("3 of 5 required done") near the status control; blocked-close dialog with per-failure quick actions and permissioned "Close anyway".
• Auto-close banner on tickets with pending ticket_auto_close_state: "Will close automatically on unless there's new activity."
• Checklist activity (check/uncheck, template applied, auto-close warning/ close) renders in TicketActivityTimeline.tsx.

8. Security / permissions

• Gate override requires ticket:close_override (checked server-side via hasPermission(user, 'ticket', 'close_override')).
• Template management rides existing settings-admin permission; checking items requires ordinary ticket update permission.
• Portal exemption is server-enforced by path, not client-asserted.

9. Rollout / migration

• All new tables and the permission ship in standard knex migrations; no backfill required. Boards without a board_close_rules row (or with is_enabled = false) behave exactly as today.
• Auto-close affects only boards where an admin creates an enabled rule.

10. Open questions

• Required-fields allowed set: start with category, subcategory, priority, assignee — extend later if asked.
• Whether checklist REST endpoints are needed for the mobile app (deferred, see non-goals).

11. Acceptance criteria (definition of done)

• A board with all gates enabled blocks closure from MSP UI (single + bulk) and REST API when any gate fails, listing every unmet condition; closure succeeds once conditions are met.
• A user with ticket:close_override can close anyway; the override with failure list appears in the ticket audit log. A user without it cannot.
• Checking a checklist item records and displays who/when; unchecking clears it and leaves an audit trail. Required items gate closure; optional don't.
• Applying a template copies its items once (idempotent); auto-apply rules attach templates on creation and board/category change.
• A ticket in a rule's trigger status with no activity for inactivity_days is closed by the scan with a system comment, and all normal closure side effects fire (email, SLA resolution, surveys, webhooks). A customer reply before the deadline cancels the pending close; the warning email goes out once at the configured lead time.
• Portal status changes to a closed status set is_closed/closed_at/ closed_by and publish TICKET_CLOSED, without gate enforcement.
• All features in features.json implemented; all tests in tests.json passing; the manual smoke pass in SMOKE_TESTS.md executed clean against the running app.