infra(ci): split backend test job into parallel lanes (Win 2′)

[SoundMindsAI]

Summary

Ships Win 2′ of infra_pr_yml_split_backend_test_lanes. Splits the heavy backend (tests + coverage) job into three parallel jobs:

Old	New	Time	Service containers
backend-unit-fast	backend-unit (unit with -n auto + cov)	~1 min	None
backend (tests + coverage)	backend-heavy (contract + integration serial + cov)	~7-8 min	Postgres + Redis + ES + OS
(n/a)	backend-cov-gate (combine + 80% gate + XML)	~30s	None (needs: both above)

Expected wall-clock recovery: ~1.5 min per run, doubled (~3 min) on the Gemini-fix re-push cycle.

Why now

The idea file's explicit deferral condition — "Pick up only when the integration layer becomes the binding CI constraint" — is met. Per the per-job timing analysis from today's 12-PR session:

Job	Avg	Critical path?
backend (tests + coverage)	9m20s	YES — sole bottleneck
frontend (lint + typecheck + tests + build)	3m32s	No (parallel)
static-checks (frontend)	3m07s	No (parallel)
docker buildx (api)	1m52s	No
6 other jobs (static-checks, license, generated, fast-lane)	≤45s each	No

Backend tests are 80% of wall-clock; everything else finishes in parallel ~6 min earlier. The operator's pain was real: ~10 min wait per push, doubled on the Gemini-fix re-push cycle.

Coverage plumbing

coverage combine pattern requires two pyproject.toml changes:

1. [tool.coverage.run] parallel = true — pytest invocations now write .coverage.<host>.<pid>.<random> files instead of one .coverage. Required so the unit + heavy lanes' data don't collide when combined.
2. New [tool.coverage.paths] section — maps per-runner absolute paths (/home/runner/work/relyloop/relyloop/backend/...) back to the canonical backend/ source. Required for cross-job combine to deduplicate correctly.

Verified locally with coverage.py 7.x: two parallel runs produce 2 uniquely-named .coverage.* data files; coverage combine merges cleanly into a single combined report.

What stays the same

• The three verify_*.sh shell scripts (enum source-of-truth, demo slug parity, install builds-all-services) stay in backend-heavy — they import the project venv that uv sync materializes there.
• SKIP_HEAVY_CI kill-switch: all three new jobs honor vars.SKIP_HEAVY_CI != 'true'. Skip mode → unit lane still runs (preserves fast feedback); heavy + cov-gate skip.
• 80% coverage threshold from pyproject.toml's [tool.coverage.report] fail_under = 80 — coverage report honors it from backend-cov-gate.

Defers (intentional)

Win 3 — split integration tests by required service container (integration:postgres / integration:elastic / integration:opensearch lanes). Higher-value win but larger blast radius (pytest markers + per-shard service-container topologies). idea.md flipped to "Win 2′ shipped; Win 3 deferred." Folder stays in planned_features/02_mvp2/.

The one user-facing UX change

Previously the coverage report appeared inline in the heavy backend job's output. Now it appears in the backend-cov-gate job's output. A developer hunting a coverage regression in the PR Checks UI clicks one more level to see the missing-line report.

Diff scope

.github/workflows/pr.yml                       +173/-34
pyproject.toml                                 +20/-0
docs/.../infra_pr_yml_split_backend_test_lanes/idea.md  +4/-2
docs/00_overview/{MVP2_DASHBOARD,backlog_dashboard,...}  auto-regen (10 files)

Dashboard regen is the standard side effect of the idea.md status flip — landed in the same commit per the mvp1-dashboard-regen pre-commit hook + the project's two-shot-commit pattern.

Test plan

• python -c "import yaml; yaml.safe_load(open('.github/workflows/pr.yml'))" — YAML parses; 12 jobs total.
• grep confirms the new triplet (backend-unit, backend-heavy, backend-cov-gate) at expected line numbers.
• Pre-commit (check toml + dashboard regen) — clean.
• Local coverage parallel + combine smoke test — confirmed.
• CI backend-unit — should run in <2 min with -n auto + cov instrumentation.
• CI backend-heavy — should run in ~7-8 min (down from ~9.5 min after unit tests removed).
• CI backend-cov-gate — should download both artifacts, combine, gate against 80%.
• CI wall-clock — total ~8 min (down from ~9.5 min).

🤖 Generated with Claude Code

[gemini-code-assist]

Code Review

This pull request updates the RelyLoop release roadmap and backlog dashboards to reflect the shipping of the infra_pr_yml_split_backend_test_lanes feature. It also configures coverage settings in pyproject.toml to support parallel coverage combining across split backend test lanes. Feedback points out that enabling parallel = true globally in pyproject.toml degrades the local developer experience by cluttering the repository root and breaking standard local coverage commands, and suggests handling coverage file renaming within the GitHub Actions workflow instead.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.

[gemini-code-assist]

Enabling parallel = true globally in pyproject.toml degrades the local developer experience in two ways:

1. Running tests locally will generate unique .coverage.<host>.<pid>.<random> files on every run, which will accumulate and clutter the repository root unless manually cleaned up.
2. Standard local commands like coverage report or coverage html will fail or show no data unless the developer explicitly runs coverage combine first.

Since the parallel lanes (backend-unit and backend-heavy) run on completely separate GitHub Actions runners, they do not need to generate parallel coverage files on the same machine. Instead, you can keep parallel = false (the default) for a clean local developer experience, and handle the naming in CI by renaming the .coverage file before uploading it or after downloading it in the gate job.

For example, in your GHA workflow:

• In backend-unit: rename .coverage to .coverage.unit before uploading.
• In backend-heavy: rename .coverage to .coverage.heavy before uploading.
• In backend-cov-gate: download both as .coverage.unit and .coverage.heavy into the same directory, then run coverage combine.

[SoundMindsAI]

Adjudication of 1 Gemini finding on 3797ef5e

#	File:Line	Severity	Verdict	Resolution
1	pyproject.toml:249 (parallel=true degrades local dev)	MEDIUM	Accept	Removed parallel = true from [tool.coverage.run]. Per-lane unique filenames are already achieved via COVERAGE_FILE=.coverage.{unit,heavy} env vars in pr.yml — parallel mode globally was unnecessary AND a real DX hazard (.coverage.<host>.<pid>.<rand> clutter on every local pytest --cov run, local coverage report showing no data without a manual coverage combine). Kept [tool.coverage.paths] mapping (still required for cross-runner combine). Updated 3 pr.yml comments that referenced the now-defunct parallel-mode intermediates. Validated against the previous green run (#27647170477) which combined to 82% — the design works without parallel = true set globally.

Wall-clock data from the previous green run

Metric	Before (today's earlier runs)	After (this PR)	Δ
backend (tests + coverage) → split lanes	9m20s avg	8m14s heavy + 56s unit + 24s gate	—
Total wall-clock critical path	9m20s avg	8m49s	−31s
Combined coverage	(whole-suite)	82% (2 files combined)	passes 80% gate

The savings are modest (~30s) — less than the idea file's ~1-1.5 min upper-bound estimate — because the heavy lane (contract + integration alone) took 8m14s vs my prediction of ~7-8m. The unit-tests fraction of the original suite was smaller than I'd modeled.

The CI re-run on 81983973 should preserve this 8m49s wall-clock with the cleaner pyproject configuration.