Lane Policy

Lane Policy

A lane is one test tier with its own command, its own trigger, and its own coverage participation. Lanes exist because test tiers have genuinely different costs: a suite that takes 90 seconds and needs a browser cannot gate every task completion, and a suite that takes 900 milliseconds should not wait for one that does.

This is a separate axis from the assertion hierarchy in policy-core. That hierarchy asks how strongly does this test verify anything. This skill asks at what level does this behavior get verified. A test can be Level 1 in a unit lane or Level 7 in an e2e lane; both questions must be answered for every test.

The four levels

Additional lanes when a repo warrants them: smoke (a handful of checks against a live environment, ["manual"]), load (["manual"]), security (["push"]).

Where a behavior belongs

Assign each behavior to the cheapest lane that can actually verify it. Not the cheapest lane it can be written in — the cheapest lane where a failure would be real.

The rule that decides borderline cases

If the test would still pass when the real collaborator is broken, it belongs one lane higher.

A test that mocks the database and asserts expect(mockQuery).toHaveBeenCalledWith(sql) passes when the SQL is invalid. That behavior is not verified at unit level and must have an integration test, or it is not verified at all.

The mock-boundary obligation

policy-core requires that mocking a system boundary is paired with an integration test covering the real path. Lanes are what make that requirement checkable instead of aspirational.

When a unit test mocks a boundary:

1. Name the boundary in the test matrix (Mock boundary: field).
2. Name the integration test that covers the real path.
3. That integration test lives in the integration lane.
4. review-gate verifies the pairing exists.

A repo with mocked boundaries and no integration lane has an unmet obligation. That is a finding, not a style preference — say so during /tdd-guardian:init and during review.

Trigger assignment

Bind a lane by its cost and its dependencies, not by its name:

Trigger semantics:

• taskCompleted — the hook runs these lanes when Claude finishes a task. This is the tight loop; anything slow here makes the plugin unusable.
• commit — checked for freshness before git commit. Not run automatically.
• push — checked for freshness before git push, gh pr create, and publish commands. push subsumes commit: pushing requires everything a commit requires, plus the push lanes.
• manual — only ever runs via /tdd-guardian:gate <lane>.

When unsure, choose the slower trigger. A fast suite on push is mildly annoying; a slow suite on taskCompleted makes people disable the plugin.

Coverage participation

coverage: "include" means the lane's report joins the merged total that thresholds are checked against. coverage: "none" means it does not.

Rules:

1. Each contributing lane needs its own coverageSummaryPath. Two lanes writing the same file means the second overwrites the first, and coverage is silently undercounted.
2. E2E lanes default to none. Browser coverage needs an instrumented build and a browser-side collector. Unless that already exists, an e2e lane contributes nothing, and configuring it as though it does corrupts the totals.
3. Prefer per-line formats when more than one lane contributes. LCOV, Cobertura, JaCoCo, coverage.py JSON, and coverage-final.json carry per-line data and merge as a true union. Summary-only formats fall back to a weighted average that counts a shared line once per lane. The gate reports which method it used and flags the approximate one.
4. Thresholds apply to the merge, not to any single lane. Do not set per-lane thresholds; that reintroduces the coupling lanes exist to remove.

Coverage does not transfer across lanes

An e2e suite that walks the whole application does not make the unit lane's uncovered branches covered. If e2e coverage is not collected, those branches are uncovered — that is accurate, not pessimistic. Adding e2e coverage to raise the number, without the instrumentation to make it real, is the coverage equivalent of a wiring-only test.

Anti-patterns

Minimum viable configuration

A repo needs exactly one lane to be configured. Do not invent an integration lane for a pure library with no I/O, or an e2e lane for a CLI with no UI. Lanes describe what the repo has; they are not a checklist to fill in.

The honest progression:

Scope

Covers the test-level taxonomy — which behavior belongs in a unit, integration, e2e, or contract lane, how lanes bind to gate triggers, and how each lane participates in coverage.

Does NOT cover: