resolutionflow/.ai/HANDOFF.md

HANDOFF.md

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

Active task: Land PR #150 (the consolidated CI-recovery PR), then enable backend + e2e gates on main. See CURRENT_TASK.md.

Branch: fix/ci-workflow-config → PR #150. PRs #151 and #152 were closed and consolidated into this branch — one PR is easier to land than three stacked ones, and the user got tired of waiting on serial CI runs of intermediate states.

Runner setup: Three Gitea Actions agents are registered on the homelab box, so backend / frontend / e2e jobs run in parallel instead of serializing on a single agent. Combined with the xdist parallelization in this PR, the previous 1h 14m wall-clock should drop to ~9–12 min.

What's on PR #150's branch (consolidated)

Eight commits, all CI-recovery work that landed together because they were inter-dependent:

1. Codex's 49f8856 wip(handoff): restore backend suite to green — fixes the 54 real backend test failures left after #149.
2. Workflow correctness: DATABASE_TEST_URL env, actions/upload-artifact v3 pin (Gitea Actions doesn't support v4+).
3. Test-fix + cheap CI wins (e976fb4): mocks _extract_template_parameters in test_record_decision_persists_and_bumps_state_version so it doesn't need an AI provider key; pip + npm caches; --cov-report=term-missing dropped (the custom display step parses JSON); --maxfail=10 so structural breakage exits fast.
4. Postgres port-collision fix (1bd43ab): dropped ports: 5432:5432 host mapping. With three Gitea runner agents now active, two parallel jobs would race on 0.0.0.0:5432. Tests connect via the postgres service-DNS hostname, not the host, so the mapping wasn't actually needed.
5. pytest-xdist with per-worker DBs (7f71436): pytest-xdist==3.6.1 added; conftest.py derives a per-worker DB URL from PYTEST_XDIST_WORKER and creates it synchronously on first import. Verified on PR #151's CI run before consolidation: 22m serial → 9m37s on the 4-core runner.
6. Five e2e selector updates (69f2a37): drift from the FlowPilot/PSA migration. Sessions → Session History, Account Settings → Account Management, /assistant accepts /pilot, "Flow Sessions" tab clicks for ticket/client filtering and Resume on /sessions.

Immediate next steps

1. Watch PR #150's CI on its latest sha (69f2a37). Backend should run ~9 min via xdist; frontend ~6 min; e2e ~5 min with the selector fixes.
2. Merge PR #150 when all three jobs are green.
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. Then enable CI / e2e (pull_request) — same PATCH, append to the list. Verify e2e is reliably green for at least one PR run before locking it in.

PRs #151 (fix/ci-pytest-xdist) and #152 (fix/e2e-test-selectors) were closed as superseded by this PR.

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.