resolutionflow/.ai/HANDOFF.md

HANDOFF.md

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

Active task: Land three open CI PRs (#150 + #151 + #152), then enable backend + e2e gates on main. See CURRENT_TASK.md.

Branches: Three open PRs, all independent of each other for correctness:

• fix/ci-workflow-config → PR #150
• fix/ci-pytest-xdist → PR #151 (stacked on #150 for context but mergeable on its own)
• fix/e2e-test-selectors → PR #152

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

Three open PRs

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.

PR #152 — fix/e2e-test-selectors → main

Carries: five Playwright e2e selector updates against the current UI. The drift was inherited from the FlowPilot/PSA migration:

• Sessions → Session History (page heading)
• Account Settings → Account Management (page heading)
• /assistant → /pilot (Phase 1 route rename; redirect still works)
• Flow-session filtering and the Resume button moved behind the "Flow Sessions" tab on /sessions (default tab is "AI Sessions")
• resume.spec.ts no longer starts at /trees — Resume button rendering moved to the session card on /sessions

No product-code changes. Pure test updates.

Immediate next steps

1. Merge PR #152 first. Smallest, lowest risk, no shared file with the other two PRs.
2. Merge PR #150 next. Backend test suite should be fully green (1076 passed, 0 failed, 0 errors).
3. Merge PR #151 last. Backend job time drops to ~4–6 min on the runner.
4. 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)"]}'
   

5. 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.

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.