The Requirements Donkey + PPI — open standard & reference implementation

The public, verifiable home of the PPI (Polysemy Preservation Index) and the Requirements Donkey that computes it. Every number on doloop.io/ppi recomputes byte-identically from these files. No model sits in the verdict path.

What's here

• PPI_STANDARD.md — the open standard: the formula, the 6 dimensions, the versioned inputs.
• reqdonkey/ — the reference implementation (deterministic):
  • dim1.py code-internal consistency (validation taint via the Semgrep witness; error-handling
    • resource-cleanup + type-hints via ast; a non-adoption FLOOR so unused readings aren't penalized) · dim2.py doc-reader (reqlex@v1 lexicon + RFC/CWE refs + undoc-API) · dim3.py code↔doc concordance + the provenance tell · dim4.py spec-conformance (vendored MUST clauses; Heartbleed vs RFC 6520 §4) · ppi.py the scalar · ratchet.py the per-tenant memory · record.py the unified Requirement (3 provenance sources, one shape).
• THEORIES.md — the falsifiable ledger: every claim has a test that could have failed.
• ppi_benchmark.json — the published corpus + PPI rows.
• global_norms.py / global_norms.json — the global norms derived from the corpus (dim 6).
• designs/ — the design recommendations behind each dimension.

Install + run (local, zero-exfiltration)

pip install -e .               # from this directory; PyPI name `reqdonkey` (publish pending)
reqdonkey /path/to/repo        # the PPI, the inferred requirements, and the gaps
reqdonkey /path/to/repo --json

Same repo + same versioned inputs (ppi@v0, reqlex@v1, classes@v0, the vendored specs, the pinned witness) → byte-identical PPI, gaps, and provenance tell.

Badge

Show your construction score. In CI, emit the shields endpoint JSON and serve it (commit it, or publish to a gist / Pages):

reqdonkey . --no-ratchet --badge > ppi-badge.json

Then in your README:

![PPI](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/OWNER/REPO/main/ppi-badge.json)

Color tracks the global bar (doloop.io/ppi): brightgreen ≥ 0.85, green ≥ 0.78, yellow ≥ 0.6.

Reproduce the benchmark + the global norms

modal run modal_benchmark.py     # the corpus (or run reqdonkey per repo)
python3 global_norms.py          # the global norms from the corpus

The method (why it's a moat, not a tool)

Witnesses (Semgrep today; Infer/CodeQL next) do the dataflow — the commodity a competent engineer gets for free. doloop's layer is the part no analyzer does: it infers the requirement from the codebase's own consistency (≥4 sites, ≥70% adherence → the norm; deviations = gaps; otherwise no requirement — no crying wolf), reads the docs and the governing specs, derives the global norms from the corpus, and collapses everything to the reproducible PPI. The inference + the 6-dimension framework + the published standards are ours; the witness is anyone's.