# Regression Runbook

## Purpose

This runbook describes how NexusCRM regression assets should be executed over
time once they are implemented.

The repository currently has pieces of this system, but not yet a complete,
enforced regression program. This document is the target operating model.

## Execution Model

### 1. Fast API Regression

Intended environment:

- PR CI
- merge-to-main CI
- local developer verification

Characteristics:

- fast enough for frequent execution
- deterministic enough to fail loudly
- narrow enough to point to one behavior or engine invariant

Candidate commands:

- `make test-e2e-api`
- targeted `tests/e2e-api/runner.py --scene ...`
- focused Go integration suites where they are a better fit

Future expectation:

- high-signal API regression assets should be gradually promoted into required or
  at least standard CI paths
- exemptions should be visible and time-bounded

### 2. UI / Runtime Regression

Intended environment:

- staging inspection
- scheduled nightly or daily runs
- release-readiness checks
- refactor milestone verification

Characteristics:

- slower
- more environment-sensitive
- closer to real user behavior
- better at catching contract drift, render drift, and interaction regressions

Candidate assets:

- Playwright suites under `tests/e2e/**`
- browser-driven admin/setup checks
- runtime readback checks
- scenario suites covering full business journeys

### 3. Scenario Regression

Scenario checks should be treated as a special class of runtime regression.

Recommended use:

- before merging large refactor milestones
- before release candidates
- on staging after metadata or control-plane changes
- when a flow spans multiple objects or permission boundaries

## Failure Handling

### Fast API Regression Failures

Default response:

1. treat as code or engine regression until disproven
2. localize the exact case or scene
3. determine whether the failure is product drift, fixture drift, or infra drift
4. either fix immediately or record explicit regression debt

### UI / Runtime Regression Failures

Default response:

1. confirm whether the failure is reproducible
2. capture enough evidence for shared review
3. classify whether it is UI-only, metadata/config drift, backend regression, or
   environment instability
4. decide whether to fix immediately, quarantine, or downgrade to backlog with
   explicit owner

## Promotion Rules

When a regression asset proves repeatedly useful, consider promoting it:

- from ad hoc local use -> documented backlog item
- from backlog item -> implemented runtime check
- from optional runtime check -> scheduled staging inspection
- from scheduled staging inspection -> CI candidate, if runtime cost is acceptable

## Ownership Expectations

- The author of a high-risk fix should make the initial regression classification.
- Reviewers should challenge missing regression follow-up when the changed
  behavior is obviously high-risk.
- Curators or maintainers may later rebalance which assets belong in CI versus
  slower inspection loops.

## Worktree Operational Notes

Regression work is often done from dedicated git worktrees. Two recurring
operational pitfalls are worth handling explicitly:

- A worktree may not have its own `.env`, even when the main repository root
  does. If a task needs `gh`, GitHub API access, or other local credentials,
  confirm where the token source actually lives before running the command.
- Occasional `index.lock` failures in a worktree are often transient. First
  check whether the reported lock file still exists and whether any active git
  process is using that worktree. If the lock path is already gone, retry once
  before treating it as a stale-lock cleanup problem.

## Current Constraint

Today, this repository already has:

- API case infrastructure
- scenario infrastructure
- partial Playwright coverage
- issue-specific regression hints scattered across docs and historical fixes

What is still being built is the operating discipline that connects:

issue fix -> regression classification -> backlog -> implementation -> recurring execution