ADR-039 — 4-Lane CI Topology (budget-scoped testing)

Status: Accepted (2026-07-16) Date: 2026-07-16 Related: #4347 (removed PR checks on dev), #3585 (sharded coverage), #1913 (suite sharding) Team guide: docs/guides/ci-cd-4-lanes.md — the short day-to-day version of this ADR

Context

CI ran the full suite (8 API shards with coverage, frontend build, agent tests, live OpenRouter evals, a macOS-native connector job at 10× billing) on EVERY push to dev — 172 runs in the week of 2026-07-08 ≈ 13,000 Linux-min-equivalents. Measured change locality: 38% of merges touch api/, 33% frontend/, 3% agent/, 6% remote-desktop-agent/, 29% none of them. PRs into dev ran no CI at all (#4347), so compile/type/unit breakage landed on dev routinely.

The team is moving to a weekly release cadence (staging cut Monday 06:00 UTC, prod Wednesday 06:00 UTC). Motto: "keep prod stable; stability derives from proper testing on staging". A release-branch model was considered and DEFERRED — the dev → staging → main branch flow stays.

Decision — four lanes

Lane	Trigger	Runs	Required?
1 Fast gate	PR → dev (pr-checks.yml)	lint, compile, UNIT tests (no containers), migrations check when api/migrations/** or api/src/database/** touched	YES — PR Gate check
2 Post-merge	push → dev (ci.yml)	integration suites, PATH-SCOPED to touched services; unit lane re-run; no coverage; no live evals; macOS connector only on remote-desktop-agent/** changes	dev has no protection gate; red = fix forward
3 Promotion	PR → staging/main (ci.yml)	full unscoped suite + live evals (advisory) + trufflehog secret scan (+ e2e-smoke.yml, unchanged)	YES — CI Success
4 Nightly	schedule (nightly.yml → workflow_call ci.yml)	FULL suite with coverage thresholds on merged report + live evals + full connector run	Slack digest on failure

Manual full run any time: gh workflow run ci.yml --ref <ref> [-f coverage=true] [-f live_evals=true].

Mechanics

• Unit/integration split: api/jest.classify.js classifies specs at config-load time by infrastructure tokens (DataSource, DATABASE_URL, REDIS_URL, ioredis, BullModule.forRoot, .listen(, …) with // @jest-lane unit|integration override markers. Unit lane (jest.config.unit.js) runs parallel workers with NO DATABASE_URL/REDIS_URL — misclassification fails loudly. Integration lane (jest.config.integration.js) keeps --runInBand + service containers. jest.config.shard.js (full suite + coverage) is now nightly-only. Split at introduction: 482 unit / 152 integration of 634.
• Path scoping on pushes: .github/actions/ci-scope classifies merge-base(before, sha)..sha; unusable SHAs or merge-base failure fail OPEN to full CI. Any .github/ change → full CI.
• Coverage ratchet moved to nightly (accepted trade: a coverage regression is flagged next morning, not at merge).
• Live evals: advisory (continue-on-error, outside ci-success) — run on promotion PRs and nightly, never on pushes.
• Secret scanning: trufflehog diff scan on promotion PRs (gitleaks was dropped when it went paid). Dependency/CVE scanning is a separate issue.

Consequences

• ~60–70% billed-minute reduction at current velocity; PR feedback in ~5 min.
• Integration failures in untouched lanes surface at nightly/promotion, not per-merge (accepted; scoping is conservative and .github changes run full).
• New spec files with infrastructure usage MUST be detectable by the token list or carry // @jest-lane integration — the fail-loud unit lane enforces this automatically.
• Branch protection on dev must require the PR Gate check (repo admin, after the first pr-checks.yml run has reported). Read-modify-write the protection settings — the API PATCH replaces the whole required-checks list.