# Regression Strategy

## Purpose

This document defines the regression model for NexusCRM after issue fixes have
been merged but before large-scale refactors land.

The goal is not "more tests". The goal is durable protection for the parts of
the product that have already been repaired in real work and are therefore at
high risk of being broken again by future implementation or refactor effort.

## Two Regression Tiers

NexusCRM regression coverage is intentionally split into two tiers.

### Tier A: Fast API Regression

This tier is designed for:

- fast feedback
- deterministic execution
- CI integration
- narrow failure localization

Typical assets:

- `tests/e2e-api/cases/**`
- API-oriented integration tests
- contract-level request/response checks
- setup/verify assertions that can run without a browser

Use this tier when the repaired behavior can be proven through API calls,
database readback, or engine-level assertions without relying on visual UI
interaction.

### Tier B: UI / Runtime Regression

This tier is designed for:

- user-visible behavior
- metadata-driven rendering
- admin/setup flows
- long-path business journeys
- staging or production-style inspection

Typical assets:

- Playwright or browser-driven checks under `tests/e2e/**`
- manual or scripted runtime inspection checklists
- scenario suites under `tests/e2e-api/scenarios/**` when the real proof is a
  multi-step business journey rather than one request

Use this tier when the repaired behavior is only trustworthy after real UI
interaction, render verification, readback verification, or multi-step workflow
completion.

## Scenario Coverage

Scenarios are treated as part of the slower runtime tier even when they are
implemented with API calls.

Reason:

- they represent business journeys, not single endpoint invariants
- they are slower to author and maintain
- they are most useful as refactor guardrails and staging inspections

Examples:

- lead convert
- quote approval
- quote to order
- record-triggered flow end-to-end
- permission-gated business path
- setup/layout change followed by user-visible runtime effect

## What Every High-Risk Issue Must Answer

After a high-risk issue is fixed and merged, the owning engineer or agent should
answer these questions:

1. Does this need fast API regression coverage?
2. Does this also need UI/runtime or scenario coverage?
3. If neither is added now, where is the debt tracked?

If the issue changed user-visible behavior, metadata-driven behavior, security,
permissions, automation, setup/control-plane logic, or a key business flow, it
must not be left without an explicit regression decision.

## Default Placement Rules

### Add a fast API regression when:

- one request or a short request chain proves the bug is fixed
- the key invariant is about payload shape, status code, persisted fields, or
  engine response
- the behavior should be runnable in CI on every PR or merge
- the fix touched CRUD, validation, permissions, setup, or automation behavior

### Add a UI/runtime regression when:

- the acceptance criteria are visual or interaction-driven
- the bug was only visible in a browser flow
- the repair depends on metadata-driven rendering, layout behavior, or readback
- the proof requires save -> reopen -> verify persistence

### Add or extend a scenario when:

- the bug only makes sense inside a multi-step business workflow
- the risk is cross-object or cross-module
- the coming refactor is likely to break orchestration rather than a single endpoint

## Current Risk Focus

Given the current repo state and the ongoing large refactor program, the first
regression wave should focus on:

- records and metadata-driven CRUD behavior
- setup/bootstrap/control-plane readiness
- permissions and security boundaries
- approvals
- flows / validation / formula execution
- quote / order / contract / lead-convert journeys
- layout-driven runtime behavior

## Non-Goals

This strategy does not require every issue to produce every tier of coverage.

It is acceptable to:

- add only fast API coverage for narrow engine bugs
- add only UI/runtime coverage for pure render or interaction regressions
- defer a scenario while capturing it explicitly in the backlog

It is not acceptable to merge repeated high-risk fixes forever without deciding
how regression protection will be added.