<!-- Keep under ~2K tokens. Old handoffs live in SESSION_LOG.md. Do not let this file accumulate history. -->

# HANDOFF.md

**Last updated:** 2026-04-25 (America/New_York)

**Active task:** Land two stacked CI PRs (#150 + #151), then enable backend gate on `main`. See [CURRENT_TASK.md](CURRENT_TASK.md).

**Branch:** Currently on `fix/ci-workflow-config` (PR #150). The xdist work lives on `fix/ci-pytest-xdist` (PR #151), branched from #150.

## Two open PRs to land in order

### PR #150 — `fix/ci-workflow-config` → main

Carries:
- The Codex commit (`49f8856 wip(handoff): restore backend suite to green`) — fixes 54 backend test failures.
- Workflow fixes: `DATABASE_TEST_URL` env, `actions/upload-artifact` v3 pin.
- Most-recent commit (`e976fb4`):
  - Mocks `_extract_template_parameters` in `test_record_decision_persists_and_bumps_state_version` (last test failing on CI; needed an AI provider key the runner doesn't have). Verified locally — passes.
  - pip + npm caches in all three jobs.
  - Drops `--cov-report=term-missing` (the custom "Display coverage summary" step prints the same info from JSON).
  - Adds `--maxfail=10` so structural breakage fails fast.

**Expected CI on this PR:** all three jobs green for the first time in months.

### PR #151 — `fix/ci-pytest-xdist` → main (stacked on #150)

Carries (on top of #150):
- `pytest-xdist==3.6.1` in `requirements-dev.txt`.
- `conftest.py` adds `_worker_db_url` + `_ensure_worker_db_exists`. Each xdist worker gets its own DB (`resolutionflow_test_gw0`, `gw1`, …) so the per-test `DROP SCHEMA public CASCADE` doesn't race across workers.
- Workflow's pytest invocation gains `-n auto`.

**Measured locally:** backend suite goes from `22m 27s` (serial, 1076 passed) → `4m 28s` (8 workers, 1076 passed). Same exit code, same test count.

## Immediate next steps

1. **Watch PR #150 CI** on its latest sha (`e976fb4`). Both `CI / backend (pull_request)` and `CI / frontend (pull_request)` should be green. Merge if so.
2. **Watch PR #151 CI** after #150 merges. Once #151 is rebased / merged automatically, backend job time on subsequent runs should drop to the 4–6 min range.
3. **Enable backend gate** on `main` branch protection — append `"CI / backend (pull_request)"` to `status_check_contexts`:
   ```bash
   curl -X PATCH -H "Authorization: token $GITEA_TOKEN" \
     "https://gitea.resolutionflow.com/api/v1/repos/chihlasm/resolutionflow/branch_protections/main" \
     -H "Content-Type: application/json" \
     -d '{"status_check_contexts": ["CI / frontend (pull_request)", "CI / backend (pull_request)"]}'
   ```
4. **Optional: also gate `CI / e2e (pull_request)`** once that job has run cleanly a few times. The artifact-v3 fix means it can finally run; we haven't verified its actual outcome yet.

## Uncommitted state

Working tree clean (after this handoff commit).

## Branch protection on main (current)

- PR-only merges
- `CI / frontend (pull_request)` required
- Force-push blocked
- No review required (solo)

## Recently merged on main

- `f27f671` — PR #149: fix(ci): frontend lint to zero errors + test-DB schema fix + dev-deps installable
- `06593a4` — PR #148: fix(tests): repair two pre-existing bugs blocking backend CI
- `32fae2c` — PR #147: feat: FlowPilot migration — Phase 1-9 + Phase 9 bug fixes + QA fixture harness
- `16060d2` — PR #141: feat: PSA ticket management

## Open questions

- One known concern with `--maxfail=10`: if a single bad commit produces 11+ legitimate failures, CI bails before reporting them all. Acceptable trade-off — the alternative is burning 25 min on a structural break.
- pytest-xdist load distribution is the default file-scoped balance. If one worker consistently gets the slow tests, switch to `--dist worksteal` (xdist 3.x). Not worth tuning preemptively.

## Useful breadcrumbs

- `backend/scripts/seed_phase9_qa_fixtures.py` pre-bakes Phase 9 QA fixtures.
- `.gstack/qa-reports/phase9-20260424-232700/REPORT.md` — full QA report from the FlowPilot session.
- gstack is in team mode for this repo. `/browse` Chromium needs `CONTAINER=1` env (see `~/.claude/skills/gstack/browse/src/browser-manager.ts:188`).
- Per-worker test DBs accumulate on the postgres service. Cheap to leave around; cleanup if it ever bothers anyone.