# STARTHERE — mgf-test-supervisor

> **Sibling library in the Magogi Foundation federation.**
> See [README.md](README.md) for what this library does; see
> [mgf-common/FEDERATION.md](https://codeberg.org/magogi-admin/mgf-standard/src/branch/main/FEDERATION.md)
> for the federation contract.

`mgf-test-supervisor` is a budget-aware, crash-survivable, resumable
test supervisor that drives `pytest` from the **outside** — hang
detection, crash isolation, budget-aware selection, resumability,
quarantine, per-failure diagnostic bundles, and append-only JSONL
outcomes. It ships the `mgf-test-supervisor` / `mtest` CLI.

---

## For consumers (using this supervisor)

1. **Pin** as a **dev** dependency in your `pyproject.toml`:
   ```toml
   [project.optional-dependencies]
   dev = ["mgf-test-supervisor>=0.1,<0.2", "pytest-timeout>=2.3,<3"]
   ```
   See [CHANGELOG.md](CHANGELOG.md) for the current minor.
2. **Install:** `uv add --dev mgf-test-supervisor` (or `pip install`).
   You also need `pytest-timeout` for the per-test timeout that backs
   the supervisor's outer wall-clock.
3. **Wire it** — add the pytest config + markers + `.gates/` gitignore
   entry from [README.md](README.md) §"Adopting in your project".
4. **Verify** the wiring:
   ```sh
   mgf-test-supervisor --self-check   # ~35s — canned pass/fail/hang/crash
   mgf-test-supervisor --tier 0       # your tier-0 smoke tests
   ```
5. **Adopt the federation contract** — file your
   `MGF_STANDARDS_CONFORMANCE.md` per
   [DOC-15](https://codeberg.org/magogi-admin/mgf-standard/src/branch/main/docs/standards/DOCUMENTATION.md).
6. **Run** `mgf-common catch-up` periodically to verify federation
   drift; see [FEDERATION.md](FEDERATION.md).

---

## CLI quick reference

| Invocation | Does |
|---|---|
| `mgf-test-supervisor` | run all tier 0–3 tests |
| `… --tier 0` / `--tier 0-2` | run a tier or tier range |
| `… --budget 5m` | greedy knapsack of tests under a wall-clock |
| `… --resume` | resume the last interrupted run |
| `… --report` | show last run's `summary.md` |
| `… --quarantine` | show currently-quarantined tests |
| `… --self-check` | canned scenarios — verifies the supervisor itself |
| `… --fail-fast` | stop after first failing chunk |

`mtest` is a short alias for the same binary. Run state + the
append-only `run.jsonl` outcome log live under `.gates/`.

---

## For contributors

See [CONTRIBUTING.md](CONTRIBUTING.md). Standards are inherited
from [mgf-common](https://codeberg.org/magogi-admin/mgf-standard/src/branch/main/docs/standards/).

---

## Quick links

| Resource | Where |
|---|---|
| Library purpose | [README.md](README.md) |
| Release notes | [CHANGELOG.md](CHANGELOG.md) |
| Dependency manifest | [DEPS.md](DEPS.md) |
| Feedback / papers | [FEEDBACK.md](FEEDBACK.md) |
| Conformance ledger | [docs/inprogress/MGF_STANDARDS_CONFORMANCE.md](docs/inprogress/MGF_STANDARDS_CONFORMANCE.md) |
| Federation contract | [mgf-common/FEDERATION.md](https://codeberg.org/magogi-admin/mgf-standard/src/branch/main/FEDERATION.md) |
| Cross-project standards | [mgf-standard/docs/standards/](https://codeberg.org/magogi-admin/mgf-standard/src/branch/main/docs/standards/) |
