[architect] refactor: enforce behave suite environment quarantine-gate contract (new tests/unit/test_suite_environment_contract.py)

[kubestellar-hive]

Refactor

Claimed ground — exact files/functions/cluster this PR occupies:

• Adds (new file, sole change): tests/unit/test_suite_environment_contract.py
• Reads only, modifies nothing: tests/*/features/environment.py (all 14 suites), tests/shared/quarantine.py
• Tracker cluster: [architect] behave suite environment contract is unenforced convention: 14 hand-wired environment.py, quarantine gate copy-pasted, timing wired in only 10/14 #763 (behave suite environment contract) / [architect] tests/shared/timing.py is an orphaned subsystem: timings.jsonl has no consumer, DEFAULT_SLA and SLA_STRICT are never read outside their own tests #764 (orphaned timing subsystem)

No existing file is touched. git show --stat on this branch is one added file.

What this changes structurally

Every behave suite ships its own tests/<suite>/features/environment.py — 14 of
them, from 26 lines (nvidia) to 469 lines (smoke). There is no shared base and
no mixin, so the cross-cutting hooks they are all expected to honour are copy-pasted
rather than inherited, and nothing detects a suite that silently drops one.

tests/shared/quarantine.py is the gate that keeps @quarantine, @future,
@pending and @hardware_blocked scenarios from executing.
tests/unit/test_quarantine.py covers that helper thoroughly in isolation, but it
says nothing about whether any suite calls it. A suite that omits the call runs its
known-failing scenarios for real — and because those tags exist precisely because
those scenarios are known-failing, the omission does not fail at authoring time. It
surfaces later as a red E2E gate that looks like a product regression.

That drift is not hypothetical: the same copy-paste shape already produced a gap in
the sibling concern. record_start/record_end from tests/shared/timing.py is
wired in only 10 of the 14 suites — bazzite, flatcar, nvidia and security
silently record nothing. See #763 for the full matrix.

This PR converts the quarantine convention into an enforced contract. The new module
parses each tests/*/features/environment.py with ast — no imports, no behave
runtime, no VM, no selenium — and asserts three things per suite:

1. before_scenario is defined.
2. before_scenario calls skip_quarantine.
3. skip_quarantine is imported from tests.shared.quarantine and not redefined
   locally, so the skip-tag precedence stays in exactly one place.

A fourth non-parametrised guard fails if the discovery glob ever collects zero
suites, so the parametrised assertions cannot quietly become vacuous.

Scope discipline

This is enforcement only — no runtime behaviour change, no production code
touched, no suite rewired. Deliberately excluded from this PR:

• Extracting the duplicated preamble into a shared tests/shared/suite_env.py
  (proposed as step 1 in [architect] behave suite environment contract is unenforced convention: 14 hand-wired environment.py, quarantine gate copy-pasted, timing wired in only 10/14 #763) — that is a 14-file behaviour-sensitive refactor that
  needs a real E2E run behind it.
• Wiring timing into the four suites that lack it, or extending this contract to
  cover timing — that first needs the [architect] tests/shared/timing.py is an orphaned subsystem: timings.jsonl has no consumer, DEFAULT_SLA and SLA_STRICT are never read outside their own tests #764 decision on whether timing is mandatory
  at all, given nothing currently consumes timings.jsonl.
• Collapsing the three _first_value definitions
  (tests/common/features/environment.py:23, tests/kde-smoke/features/environment.py:35,
  tests/shared/ssh_config.py:28).

Verification

$ python -m pytest tests/unit/test_suite_environment_contract.py -q
43 passed in 0.80s

All 14 existing suites already satisfy the contract, so this is green on arrival.

Mutation-checked that the test is not tautological — replacing the gate in
tests/nvidia/features/environment.py with if False: produces:

FAILED tests/unit/test_suite_environment_contract.py::test_before_scenario_applies_quarantine_gate[nvidia]
AssertionError: tests/nvidia/features/environment.py: before_scenario never calls
skip_quarantine(). Every suite must apply the shared gate from
tests/shared/quarantine.py, otherwise its @quarantine, @future, @pending and
@hardware_blocked scenarios run instead of being skipped.
1 failed, 42 passed

The mutation was reverted; the diff contains only the new file.

Disjointness from open hold-gated PRs

Checked against the open snapshot for this repo via gh pr view --json title,files:

• [quality] test: add unit tests for screenshot_steps.py behave wrappers #751 [quality] test: add unit tests for screenshot_steps.py behave wrappers
  touches only tests/unit/test_screenshot_steps.py.
• [scanner] fix: ignore input-remapper in QEMU #757 [scanner] fix: ignore input-remapper in QEMU touches only
  tests/smoke/features/steps/system_health_steps.py and
  tests/unit/test_system_health_steps.py.

Neither touches tests/*/features/environment.py, tests/shared/quarantine.py, or
the new file. No overlap.

Refs #763

---

Filed by architect agent (ACMM L5 — hold-gated mode). Hold-gated: human review required.

— hive: agent=architect backend=copilot model=claude-opus-5

[codecov-commenter]

⚠️ Please install the to ensure uploads and comments are reliably processed by Codecov.

Codecov Report

❌ Patch coverage is 98.33333% with 1 line in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
tests/unit/test_suite_environment_contract.py	98.33%	1 Missing ⚠️

📢 Thoughts on this report? Let us know!