[architect] refactor: single source of truth for the results-directory contract — new tests/shared/results_dir.py; timing.py/screenshot.py/kde_faillog.py import it

[kubestellar-hive]

Refactor

Cluster claimed: the results-directory resolution contract in tests/shared.
Files touched: tests/shared/results_dir.py (new), tests/shared/timing.py,
tests/shared/screenshot.py, tests/shared/kde_faillog.py.
Function extracted: the three byte-identical private _results_dir() definitions
(timing.py:9, screenshot.py:18, kde_faillog.py:108) become one
tests/shared/results_dir.resolve_results_dir().

What changes structurally

Every artifact writer in tests/shared resolves its output directory with the same
precedence — behave userdata results_dir > env TESTSUITE_RESULTS_DIR > /tmp/results.
That rule was stated three times, byte-for-byte (same body, same docstring), with no
shared definition. Changing the precedence meant editing three copies, and only the
kde_faillog copy was directly unit-tested
(tests/unit/test_kde_faillog.py:320), so a divergence introduced in timing.py or
screenshot.py would not have been caught.

This adds tests/shared/results_dir.py exporting resolve_results_dir(context=None) and
DEFAULT_RESULTS_DIR, and rebinds the three sites to it:

from tests.shared.results_dir import resolve_results_dir as _results_dir

Importing under the existing private name means no call site and no test reference
changes — tests/unit/test_kde_faillog.py still exercises the contract through
mod._results_dir, now against the single shared implementation.

What does NOT change

Pure de-duplication. The resolution order, the userdata key, the env var name and the
/tmp/results default are all identical. No behaviour change, no feature addition.

Deliberately out of scope

tests/shared/gnome_shell_steps.py:143-144 hardcodes /tmp/results for atspi_tree.txt
and does not honour the contract at all (its reader,
tests/smoke/features/environment.py:457, hardcodes the same path independently).
Converting those two sites changes where an artifact lands when results_dir is
overridden, so it is not bundled into a no-behaviour-change refactor. It is recorded as
step 2 in the issue.

Disjointness

No open testsuite PR touches these files. Checked against the current open set:
#776 (tests/unit/test_update_coverage_snapshot.py), #774 (tests/unit/test_compose_e2e_image.py),
#757 (tests/smoke/features/steps/system_health_steps.py, tests/unit/test_system_health_steps.py),
#751 (tests/unit/test_screenshot_steps.py — the behave wrappers in screenshot_steps.py,
not screenshot.py). This PR adds no file under tests/unit/.

Validation

• ruff check tests/ scripts/ --select E,F,W --ignore E501 — All checks passed (matches the
  pr-validate.yml lint gate).
• pytest tests/unit — 1278 passed (test_validate_docs.py excluded: it fails to import on
  this machine for an unrelated pre-existing reason, scripts/validate_docs.py raising
  SystemExit(1) at import).
• python3 scripts/update_coverage_snapshot.py --check — OK, snapshot still up to date.

Refs #779

---

Filed by architect agent (ACMM L5 — hold-gated mode). Hold-gated: human review required. Do not merge without human approval.

— 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

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!