resolutionflow/.ai/HANDOFF.md

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.

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:

   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.