Groundwork

A ground-truth benchmark generator and recovery scorer for structure-inference systems.

Groundwork manufactures realistic datasets whose hidden structure — groups, causal chains, process trajectories, labels — is known by construction, feeds those datasets to any external analysis system, and measures exactly how much of the truth that system recovered. It is the answer key for a category of AI systems that, on real data, nobody can grade honestly.

Groundwork is an evaluation instrument. It generates and scores; it ships no analysis logic of its own. The system under test is always brought by the user, behind a thin adapter, and is blindfolded — it sees only observations, never the answer key.

Documents

• docs/vision.md — the why
• docs/requirements.md — the what (numbered, testable)
• docs/design.md — the how

Status

Pre-implementation. Vision, requirements, and design are drafted and reviewed. The project skeleton and quality gate are in place; the v0 build is decomposed into phased agent briefs under prompts/ and has not been run yet.

Stack (decided): Python 3.12+ · seeded numpy · pydantic · scikit-learn / networkx for scoring · typer CLI · pytest · uv. Rust-behind-PyO3 is a deferred performance escape hatch.

Layout

.
├── CLAUDE.md              # project brief, design principles, working conventions
├── Makefile               # check / lint / boundary / test / fix / install
├── pyproject.toml         # deps + ruff + pytest + the import-linter boundary contract
├── docs/                  # vision / requirements / design — the source of truth
├── prompts/               # phased agent briefs for the v0 build
├── src/groundwork/
├── tests/{unit,integration}/
└── .claude/
    ├── settings.json      # shared hooks (ruff format on edit)
    ├── rules/             # commits, testing, review-gate, pull-requests
    └── templates/         # agent coordination methodology + prompt scaffold

Getting started

make install   # uv sync
make check     # lint + boundary + test — the pre-commit gate

make check must pass before every commit. make boundary runs the import denylist that proves Groundwork ships no structure-inference logic (requirements NFR-BND-1). See .claude/rules/ for the full working conventions.