CONTRIBUTING.md

# Contributing to the physics-lint Space

The one non-negotiable rule:

> **The numbers on the page come from `demo_logic.py`, which imports no UI
> framework.**

Everything a visitor sees is produced by code the test suite exercises
directly. `app.py` and `index.html` arrange it; they never compute it. If a
number could only be produced by the UI layer, it is a number nobody has
tested, on the most public surface in the portfolio.

## What a good contribution looks like

- **A clearer refusal.** An upload the Space accepts and reports on without
  really validating, or a message that says what went wrong without saying what
  to do about it.
- **A better negative control.** The *run the negative control* button exists
  because a checker reporting 100% compliance is indistinguishable from one that
  has quietly stopped working. Both directions are shown — a law that stops
  rejecting violators has gone blind, one that starts rejecting good networks
  has gone hysterical — and anything that strengthens that is welcome.
- **A counterexample to the certified bound.** The sliders exist so a skeptical
  reader can try to refute it. Sampling cannot prove the bound; if you find a
  layout that exceeds it, that is the most useful thing you could send.

## Before you open a PR

```bash
pip install -r requirements.txt
python -m pytest tests/ -q        # 35 passed
python -u app.py                  # http://127.0.0.1:7860
```

The Gradio Lite version in `index.html` is **pinned**, because newer releases
currently fail to resolve their own `huggingface-hub` dependency inside Pyodide
— which shows up as a micropip error in the browser console rather than as
anything on the page. If you bump it, boot the built page and confirm all three
tabs work before submitting.

Every number shown must be reproducible by running the published code. The one
exception in the portfolio is labelled where it appears; do not add a second.