# Contributing — mgf-test-web (ProofWarden)

`mgf-test-web` is a Magogi Foundation sibling and **inherits the cross-project
engineering standards** from
[`mgf-common`](https://codeberg.org/magogi-admin/mgf-common).

## First read

1. [FEDERATION.md](FEDERATION.md) — the contract.
2. [SCOPE.md](SCOPE.md) — what belongs here (the warden authority + `testctl` +
   runner adapters; the base MUST stay FastAPI-free).
3. The plan + spec —
   [`mgf-fedres/docs/planning/mgf-test-web/`](https://codeberg.org/magogi-admin/mgf-fedres/src/branch/main/docs/planning/mgf-test-web)
   (`brief.md`, `spec_v0_1.md`, `console_wireframe.html`).

## Process

1. **Bug / feature:** file in [FEEDBACK.md](FEEDBACK.md).
2. **PR:** branch from main; run the gates locally:
   ```sh
   uv run --extra dev ruff check src tests && uv run --extra dev ruff format --check .
   uv run --extra dev mypy
   uv run --extra dev pytest --cov --cov-report=term-missing
   mgf-fed app-doctor --standards
   ```
3. **The single-flight invariant carries extra discipline** — it is the one rule
   that defines the product:
   - any change to the **acquire decision** (`broker.submit`) or the **lease
     registry** MUST preserve single-flight *by construction* (one in-process
     critical section; no file-lock TOCTOU) and keep every outcome an **audited
     event** (acquire / coalesce / queue / release / reclaim) — the visible proof
     the authority held;
   - the client MUST stay **fail-closed** (a down warden refuses, never runs a test
     on its own);
   - the `concurrency`-marked tests are that proof — keep them green and extend them
     when you touch the broker/daemon.
4. **Keep the base headless of the web stack** — the warden + `testctl` + runner
   adapters MUST NOT import `fastapi`/`uvicorn`/`jinja2`/`starlette`. Those belong
   to the `[web]` console extra only, so CI can install the authority without a web
   stack.
5. **CHANGELOG.md:** add an `[Unreleased]` entry.
6. **CI is generated:** never hand-edit `.woodpecker.yml`; regenerate with
   `mgf-fed scaffold mgf-test-web` (WF-13).
7. **Reviewer:** the federation owner (mgf-common maintainer).

## Release flow

Bump `pyproject.toml::version` + `mgf.test_web.__version__` → build → test →
`twine check` → commit → tag `vX.Y.Z` → push tag (CI publishes to devpi) → regen
the registry (REL-13). As a **consumer** of the `mgf-fedres` spine, re-pin to a new
spine MINOR only after it has published.
