<!-- BEGIN mgf-common auto-generated — managed by `mgf-fed catch-up`.
Edit only between this block's BEGIN/END markers if you want catch-up to
refresh your changes; project-specific content goes BELOW the END marker
in the "Project-specific lookup" section. -->

Project-specific lookup for Claude sessions. Cross-project
engineering standards live in `mgf-common`; run
`mgf-fed standards <topic>` to read any one of them.

**▶ First, run `mgf-fed agents`** — it prints the canonical
federation-wide agent briefing (always installed; `mgf-common` is a
dependency of this project). The briefing covers the federation
shape, using the library + its siblings instead of reinventing
them, the standards + docs layout, keeping this project in sync with
`mgf-fed catch-up`, and filing feedback in the relevant library's
`FEEDBACK.md` when you hit friction so the library itself can improve.

> **Project kind:** cli
> **Cornerstone library:** `mgf-common` (this project depends on it).
> **Conformance level:** declare yours in
> `docs/inprogress/MGF_STANDARDS_CONFORMANCE.md` (L1 / L2 / L3) — see
> `mgf-fed standards README` §"Conformance levels for projects".

---

## Standing instructions — every session

Claude reads this file on every session start. The rules below are
canonical; the full text lives in `mgf-common` standards docs and
is accessible via:

```bash
mgf-fed standards            # list all topics
mgf-fed standards LOGGING    # print the full doc
mgf-fed standards security   # alias also works
```

**Before writing or editing code in any of these areas, read the
corresponding topic doc:**

| Area | Topic | Run |
|---|---|---|
| API surface (public functions, modules) | API_DESIGN | `mgf-fed standards api` |
| Error handling, exceptions, retries | ERROR_HANDLING | `mgf-fed standards errors` |
| Logging, redaction, OTel | LOGGING | `mgf-fed standards logging` |
| Configuration, settings, env vars | CONFIGURATION | `mgf-fed standards config` |
| Secrets, TLS, subprocess, crypto | SECURITY | `mgf-fed standards security` |
| Tests, fixtures, isolation | TESTING | `mgf-fed standards testing` |
| Architecture, layering, replaceability | DESIGN_PRINCIPLES | `mgf-fed standards design` |
| Scope (what belongs in this project) | SCOPE | `mgf-fed standards scope` |

---

## The top-30 most-violated rules (inline so they're always in context)

These are the rules that come up most often in code review. Treat
every MUST as non-negotiable. The ID prefix tells you which doc
the full rationale lives in (DP- = DESIGN_PRINCIPLES, EH- =
ERROR_HANDLING, etc.).

### Architecture (DP-)

- **DP-01** Layering MUST be enforced: UI MUST NOT be imported by
  core; core MUST NOT import third-party SDKs that have a provider
  in front of them.
- **DP-02** Every third-party I/O dep MUST sit behind an ABC with
  a production AND a mock implementation.
- **DP-03** Domain types passed between modules MUST be frozen
  dataclasses (or pydantic `frozen=True`); never bare strings/dicts.
- **DP-04** Every public function MUST have a typed signature;
  `mypy --strict` MUST pass on `src/`.
- **DP-09** Cancellation MUST be explicit. Long-running ops take
  an explicit `CancellationToken`-like parameter; never thread-global.
- **DP-11** Async tasks MUST have an owner. Bare
  `asyncio.create_task(...)` without retention is a defect.
- **DP-12** Time MUST be UTC at every boundary. `datetime.now()`
  is forbidden; use `datetime.now(UTC)`. Naive datetimes never
  cross module boundaries.
- **DP-13** Every owned external resource MUST be released
  deterministically via context manager or `try / finally`.
  GC-based cleanup is a defect.

### Error handling (EH-)

- **EH-01** Every exception raised by app code MUST be a subclass
  of the application's base error class (typically
  `mgf.common.exceptions.AppError`).
- **EH-02** Third-party exceptions MUST be translated to typed
  application exceptions at the boundary. Use
  `mgf.common.providers.ProviderABC` + `@translate_at_seam` for
  this.
- **EH-03** When re-raising a translated exception, the original
  cause MUST be chained via `raise NewError(...) from original`.
- **EH-04** Every entry point MUST install a top-level handler
  (folded into `mgf.common.bootstrap()` automatically).
- **EH-07** Bare `except Exception:` (without re-raise or typed
  translation) MUST NOT appear except in narrow cleanup paths.
- **EH-11** Retries MUST use exponential backoff with full jitter
  and a finite cap. Use `mgf.http.RetryPolicy` (sibling `mgf-http`).

### Logging (LG-)

- **LG-01** Every module MUST acquire its logger via
  `logging.getLogger(__name__)`. No bare `logging.info(...)`.
- **LG-04** Sensitive fields MUST be redacted by the formatter
  before any sink sees them. The default
  `mgf.common.observability.Redactor` covers the canonical set.
- **LG-05** Error-level logs MUST include the exception via
  `LOG.exception(...)` or `exc_info=True`.
- **LG-08** Log messages MUST use lazy `%`-style formatting
  (`LOG.info("processing %s", x)`), NOT f-strings.
- **LG-09** Structured fields MUST be passed via `extra={...}`.
- **LG-12** Log emission MUST be cheap (≤100 µs per record).
  Heavy work belongs in the handler, not the call site. Use
  `mgf.common.observability.AsyncJsonHandler` for non-blocking I/O.

### Configuration (CF-)

- **CF-01** Application config MUST live in a single typed object
  (`mgf.common.config.BaseAppSettings`-derived). No module reads
  config files / env vars directly.
- **CF-02** Precedence: CLI flags → env vars → `.env` → on-disk
  config → typed defaults.
- **CF-05** Secrets MUST NOT live in the config file; they live in
  a vault. Use `mgf.common.vault.VaultProtocol`.
- **CF-08** `Settings` is loaded once at the entry point and
  passed down by constructor injection. No module-global singletons.
- **CF-10** Tests MUST construct `Settings` with explicit values
  (no env-var leakage).

### Security (SC-)

- **SC-01** Secrets MUST live in a Vault, never in config / env /
  source / logs / crash reports.
- **SC-02** Subprocess invocation MUST use `argv` lists with
  `shell=False`.
- **SC-06** TLS verification MUST be enabled on every outbound
  connection.
- **SC-07** Every external request MUST carry a finite timeout.
- **SC-15** Filesystem operations MUST validate against directory
  traversal via `Path.resolve()` + `is_relative_to()`.

### Testing (TS-)

- **TS-01** `tests/` MUST mirror `src/` 1:1.
- **TS-02** The unit suite MUST run with no production
  credentials, no network, no real third-party daemon.
- **TS-04** `filterwarnings = ["error"]` MUST be set in
  `pyproject.toml`.
- **TS-06** Coverage gate ≥80% project-wide; ≥90% on changed
  lines.

### API design (AP-)

- **AP-01** Public API surface MUST be enumerated explicitly via
  `__all__` at every package and module boundary.
- **AP-04** Deprecation cycle MUST be: announce → still works
  (≥1 MINOR) → removed; deprecated names emit
  `DeprecationWarning`.
- **AP-08** Public modules MUST use
  `from __future__ import annotations`; runtime-unused imports go
  in `if TYPE_CHECKING:`.
- **AP-14** Internal modules MUST NOT be imported by consumers.
  Single-underscore module names are private.

---

## Quick start — bootstrapping this project

This project depends on `mgf-common`. The canonical entry point
is `mgf.common.bootstrap()`:

```python
# src/mgf-test-supervisor/__main__.py
import mgf.common
from mgf.common.cli import run_and_translate, build_cli, dispatch

def main(argv=None) -> int:
    parser = build_cli(prog="mgf-test-supervisor")
    args = parser.parse_args(argv)
    with mgf.common.bootstrap(app_name="mgf-test-supervisor", app_version="0.1.0"):
        return dispatch(args, parser=parser)

if __name__ == "__main__":
    raise SystemExit(run_and_translate(main))
```

For test fixtures, use `mgf.common.bootstrap_for_test()`:

```python
import pytest
from mgf.common import bootstrap_for_test, AppContext

@pytest.fixture
def app_ctx() -> AppContext:
    with bootstrap_for_test() as ctx:
        yield ctx
```

For the full integration shape (settings, exceptions, observability,
recipes), see `mgf-common`'s
`docs/recipes/cli.md` (run `mgf-fed standards
components` to find it).

---

## Four green gates — every PR

Before any commit, all four MUST pass:

```bash
ruff check src tests
mypy --strict src/
pytest --cov --cov-fail-under=80
lint-imports
```

The pyproject.toml snippet generated alongside this file pre-tunes
ruff + mypy + pytest. Add `import-linter` rules for layering as
the project grows.

---

## Federation-discipline reminders (v2.8 DOC-13 / DOC-14 / DOC-15)

Three living disciplines apply to every consumer of mgf-common.
Each has a one-paragraph reminder below; the full rules live in
[`mgf-common/docs/standards/DOCUMENTATION.md`](https://codeberg.org/magogi-admin/mgf-common/src/branch/main/docs/standards/DOCUMENTATION.md).

<!-- BEGIN mgf-common: feedback-discipline -->

### Feedback discipline (DOC-13 + FB-01..FB-04)

Hit friction in mgf-common OR any federation sibling? **File a
`PAPER-NN` entry in the target repo's `FEEDBACK.md`** — not
ad-hoc emails, not lost one-off issues.

- Touches one library's surface (e.g., mgf-http retries,
  mgf-fastapi middleware) → file in that library's `FEEDBACK.md`
  (sibling-scoped per DOC-13).
- Touches federation-wide concerns (cross-sibling patterns,
  standards proposals, cornerstone APIs) → file in
  [mgf-common/FEEDBACK.md](https://codeberg.org/magogi-admin/mgf-common/src/branch/main/FEEDBACK.md).

```bash
mgf-fed feedback-howto              # how to submit + severity guide
mgf-fed feedback-howto --template   # entry template, ready to paste
mgf-fed feedback-howto --url        # canonical FEEDBACK.md URL
```

Severity guide:
- 🔴 **Blocker** — getting it wrong requires a breaking change later.
- 🟡 **High** — real quality-of-life pain, additive to fix.
- 🟢 **Nice-to-have** — real value, not urgent.
- 💭 **Aspirational** — long-term direction input.

Don't wait for permission. The maintainer triages.

<!-- END mgf-common: feedback-discipline -->

<!-- BEGIN mgf-common: adoption-discipline -->

### Adoption-tracker discipline (DOC-14 + ADP-01..ADP-04)

This project's adoption of mgf-common (which versions, which
features, which phase) lives in
`docs/inprogress/MGF_ADOPTION.md` (or `docs/MGF_ADOPTION.md`).
**Update it on every pin bump AND every closed FEEDBACK paper**
that touches this project's adoption surface (per ADP-03).

Template:
[mgf-standard/docs/recipes/mgf-adoption-md-template.md](https://codeberg.org/magogi-admin/mgf-standard/src/branch/main/docs/recipes/mgf-adoption-md-template.md).

Federation siblings: the ADP-04 carve-out exempts you — your
adoption story is the federation_roadmap + your own CHANGELOG.

<!-- END mgf-common: adoption-discipline -->

<!-- BEGIN mgf-common: conformance-discipline -->

### Conformance-tracker discipline (DOC-15 + CFM-01..CFM-04)

This project's conformance to mgf-common's standards (per-rule
✅ / 🚫 / ⏳ / N/A status) lives in
`docs/inprogress/MGF_STANDARDS_CONFORMANCE.md`. **Update it on
every standards bump in mgf-common AND on every PR that changes
code touching a conformance rule** (per CFM-03).

Declared conformance level (L1 / L2 / L3 per CFM-02): see this
project's README. Decline-with-rationale (🚫) MUST carry a
paragraph per
[principles/non-adoption-is-valid.md](https://codeberg.org/magogi-admin/mgf-standard/src/branch/main/docs/standards/principles/non-adoption-is-valid.md).

Template:
[mgf-standard/docs/recipes/mgf-standards-conformance-md-template.md](https://codeberg.org/magogi-admin/mgf-standard/src/branch/main/docs/recipes/mgf-standards-conformance-md-template.md).

<!-- END mgf-common: conformance-discipline -->

<!-- END mgf-common auto-generated. Project-specific content below

# mgf-test-supervisor — Claude Reference

Dense lookup document. No prose. Facts only.

> **Project kind:** Python CLI (the federation's canonical test runner).
> **Conformance:** L2. Tracker `docs/inprogress/MGF_STANDARDS_CONFORMANCE.md`.
> Runtime LG / CF / OB rules declined per the TS-23 stdlib-only constraint.
> **Cornerstone:** `mgf-common` — DEV dep only (schema-alignment contract); NOT a runtime dep.

**▶ First, run `mgf-common agents`** for the canonical federation briefing.
Federation contract: `mgf-common/FEDERATION.md`. Standards corpus:
`mgf-common standards <topic>` (testing/api/errors/logging/security/…).

---

## What it is

Budget-aware, crash-survivable, resumable test supervisor that drives `pytest`
from the OUTSIDE (subprocess) so it can detect hangs / crashes / freezes pytest
itself cannot. Writes one append-only JSONL record per test outcome plus a
per-failure diagnostic bundle. Federation-standard test infra (TS-22..TS-27);
the `mtest` binary every `mgf-*` sibling wires as its test driver.

---

## CLI surface

Two entry points, same binary: `mgf-test-supervisor` and `mtest`
(both → `mgf.test_supervisor.__main__:main`).

```
mgf-test-supervisor                  # run all tier 0-3 tests
  --tier 0 | 0-2 | 1-3               # tier range (parse_tier_range; 0..3, default 0-3)
  --budget 30s | 5m | 2h             # greedy knapsack under wall-clock; tier-0 always in
  --resume                           # continue from .gates/state.json (skip completed)
  --fail-fast                        # stop after first failing chunk
  --skip-quarantined (default)       # / --no-skip-quarantined / --quarantine-attempt
  --require-nonempty                 # exit 2 on empty selection (PAPER-95) — DEFAULT for explicit --tier runs (M2 Wave-2)
  --allow-empty                      # opt out of the --tier-run default above
  --quarantine-report                # print the quarantine table after the run
  --self-check                       # canned pass/fail/hang/crash (~35s); verifies supervisor itself
  --report                           # print last run's summary.md
  --quarantine                       # show current quarantine state
  -v / --verbose
```
No `--merge` flag (the runner always reconciles the full run; not a versioned behavior).

**Exit codes:** 0 clean · 1 a test failed/errored/hung/crashed · 2 supervisor
failed before completing · 3 usage error · 4 self-check failed.

**Outputs — everything under `.gates/`** (gitignore it):
```
.gates/last-run/run.jsonl          one TestRecord per outcome (append-only JSONL)
.gates/last-run/summary.md         human-readable summary
.gates/last-run/failures/<id>.txt  per-failure diagnostic bundle (one file = one failure)
.gates/last-run/junit-NNNN.xml     raw pytest XML per chunk (debugging aid)
.gates/state.json                  resume checkpoint (atomic write)
.gates/durations.json              per-test duration history + recency score
.gates/quarantine.json             quarantine state (3-of-5-in / 3-consec-out)
.gates/.lock                       advisory fcntl lock — serialises concurrent runs (PAPER-95)
```

---

## Module + file map

Package: `src/mgf/test_supervisor/` (PEP 420 namespace; sibling of `mgf.common`).

| File | Holds |
|---|---|
| `__init__.py` | `__version__`; module-map docstring |
| `__main__.py` | argparse CLI; `_find_repo_root` (walks up CWD for `pyproject.toml`), `_gates_lock`, `_handle_empty_selection`, budget parsing |
| `supervisor.py` | **core** — `RunConfig`, `Supervisor`, `collect_tests` (ONE spawn: node-ids + markers via injected dump plugin), `collect_test_markers` (derivation, no extra spawn); chunked pytest runs (50/chunk), hang→SIGTERM→SIGKILL with streaming output drain (silence-aware hang heuristic), crash isolation, SECTION_ORDER failure bundles, quarantined-record emission, resume |
| `records.py` | `TestRecord` (frozen, slotted), `SCHEMA_VERSION="1.1.0"`, `OUTCOMES`, `SEVERITIES`, `JsonlWriter`, `read_jsonl`, `now_iso`, `severity_for_outcome` |
| `tiers.py` | `MARKER_TIER`, `DEFAULT_TIER=1`, `TIERS`, `tier_for_markers` (highest-wins), `auto_tier` (5× typical → bump up, never below marker floor), `parse_tier_range` |
| `selection.py` | `TestCandidate`, `SelectionReport`, `build_candidates`, `select_tests` (pure: tier filter + quarantine skip + greedy value/cost knapsack) |
| `quarantine.py` | `QuarantineStore` (TS-25: 5-window, 3-fail in, 3-consec-pass out); atomic JSON |
| `durations.py` | `DurationStore` — rolling last-5 history, `estimated_duration_s`, `recency_score`, `auto_tier_overrides`; atomic JSON |
| `diagnostics.py` | best-effort capture (daemon_state, wchan, dmesg, env fingerprint); every fn returns `str`, NEVER raises |
| `self_check.py` | `run_self_check` — temp `tests/` tree with canned pass/fail/hang/crash, isolated `.gates` |

---

## Public API

Runtime is **stdlib-only (TS-23)** — imports no third-party package and no
`mgf-*` sibling; `pytest` is invoked as the consumer's subprocess, not imported.

Schema-alignment is a **DEV-dep relationship, not runtime**:
`mgf.test_supervisor.records.TestRecord` / `SCHEMA_VERSION` and
`mgf.test_supervisor.tiers.MARKER_TIER` are deliberately duplicated to mirror
`mgf.common.testing.{TestRecord, SCHEMA_VERSION, MARKER_TIER}`. Consumers parse
JSONL via `mgf.common.testing.TestRecord.from_jsonl_line(...)`; this library
imports nothing from `mgf-common` at runtime.

Repo-root override: `MGF_TEST_SUPERVISOR_REPO_ROOT`.
Daemon-probe override: `MGF_TEST_SUPERVISOR_DAEMON_PROCESS_NAME`.

---

## Build / test (self-hosting caveat)

This project **is** the federation test runner — it cannot supervise itself, or
a broken supervisor could mask a broken supervisor. The CI gate runs **plain
pytest directly** (bootstrap-free), not `mtest`:

```sh
.venv/bin/python -m ruff check src/ tests/
.venv/bin/python -m mypy --strict src/
.venv/bin/python -m pytest
.venv/bin/python -m coverage report
```

`mtest --self-check` is the dog-food path (verifies pass/fail/hang/crash
detection), but it is NOT the gate. Coverage floor `fail_under=45` is a ratchet
(self-check exercises runtime via subprocess, uncaptured by in-process coverage;
true figure higher). `filterwarnings=["error"]`; markers strict; per-test
`timeout=30`, `faulthandler_timeout=60`.

---

## Dependencies / Consumers (DEPS.md)

**§1 depends on:** runtime = *(none)* — stdlib-only (TS-23). DEV-only:
`mgf-common` (unpinned; `TestRecord`/`MARKER_TIER`/`SCHEMA_VERSION` alignment
contract), `pytest>=8.0`, `pytest-asyncio>=0.23`, `pytest-timeout>=2.3,<3`,
`pytest-cov>=5.0`, `ruff>=0.4`, `mypy>=1.10`.

**§2 consumers:** **every `mgf-*` sibling** wires `mtest` as a **dev dep**
(mgf-common + fastapi + sqlalchemy + alembic + http + apiprobe + livepush +
tele-core + tele-teltonika + auth), plus consumer apps on the tier model
(PlasmaMapper reference adopter). Coupling is the pinned `[dev]` entry + the
JSONL/CLI contract, NOT Python import sites — survey via
`grep -rl mgf-test-supervisor */pyproject.toml`. A `MARKER_TIER` / CLI change
ripples to every adopter — walk DEPS §2 before a breaking change.

---

## Conventions / gotchas

- **TS-22..TS-27 spec** lives in `mgf-standard/docs/standards/TESTING.md` (§13.11
  marker taxonomy, §19 reuse). Tier model: 0 smoke / 1 contract·property·
  regression·fuzz / 2 concurrency·conformance·use_case·integration / 3
  perf·stress·e2e. Highest-marker-wins; unmarked → tier-1. (`slow` removed
  in M2 Wave-2 — deprecation completed.)
- **Schema-version alignment.** Any change to `TestRecord` shape, `MARKER_TIER`,
  or `SCHEMA_VERSION` MUST land in BOTH this repo and `mgf.common.testing` in the
  SAME commit/wave. Pinned by `tests/unit/test_alignment_with_mgf_common.py`
  here + `tests/unit/testing/test_supervisor_alignment.py` in mgf-common — drift
  fails CI on both sides.
- **Empty-tier fail-loud (PAPER-95).** A green result that tested nothing is
  worse than red. Tests-exist-but-filtered-out warns loudly; explicit `--tier` runs exit 2 by
  default (`--allow-empty` opts out; `--require-nonempty` forces it elsewhere). `.gates/.lock` (fcntl) serialises concurrent `mtest` runs.
- **Class-test reconciliation (PAPER-96).** Track the open reconciliation of
  class-scoped test IDs in run aggregation (see records.py reconciliation; kept current with the source).
- **Plugin-flag hygiene (L6 lesson).** Use `-p no:<plugin>`, NEVER plugin flags
  like `--no-cov` (unknown-flag → "collection returned no tests" with zero
  diagnostic). Pinned by `tests/unit/test_plugin_hygiene.py`.
- **Collection-failure visibility.** Empty collect + non-zero pytest MUST print
  pytest stderr, never silently return `[]`.
- **Repo-root discovery.** Walk up CWD for `pyproject.toml` — NEVER regress to
  `Path(__file__).parents[N]` (points at site-packages once installed).
- **No third-party runtime import, ever** — adding one breaks the federation
  contract and defeats the tool on broken venvs.
- **Commit trailers:** `Signed-off-by: Bassam Alsanie` + `Co-Authored-By: Claude`.

---

## Federation cross-refs

- `mgf-common agents` — canonical federation briefing.
- `mgf-common/FEDERATION.md` — the contract.
- `mgf-common standards testing` — TS-22..TS-27 full spec.
- Adoption recipe: `mgf-common/docs/recipes/test-supervisor-adoption.md`.
- Rollout history: `mgf-common/docs/inprogress/SUPERVISOR_ROLLOUT.md`.
- Feedback: file PAPER-NN in this repo's `FEEDBACK.md` (sibling-scoped) or
  `mgf-common/FEEDBACK.md` (federation-wide). `mgf-common feedback --template`.
