atoll

atoll is a strict Python package generated by scaffold-guard.

The implemented V1 analysis slices scan Python projects for top-level symbols, dynamic blockers, mypy diagnostics, dependency edges, conservative island candidates, poison residue, generated sidecars, managed shims, mypyc builds, and runtime verification:

uv run atoll scan .

The scan command writes .atoll/report.json and .atoll/report.md.

Sidecars

uv run atoll enable app.ranking --symbols score_user,rank_candidates
uv run atoll enable app.ranking --symbols score_user,rank_candidates --build
uv run atoll generate --check
uv run atoll verify
uv run atoll build --clean-first --inplace
uv run atoll verify --require-compiled

Atoll writes configuration to .atoll.toml, generated modules like _ranking_atoll.py, and managed shim blocks marked with BEGIN ATOLL MANAGED.

Explain And Trial

uv run atoll explain app.ranking
uv run atoll explain app.ranking::score_user
uv run atoll trial --top 3 --test "pytest tests"
uv run atoll trial --top 3 --test "pytest tests" --benchmark "pytest benchmarks"
uv run atoll clean --all

Trial mode uses a temporary overlay and currently supports pytest commands such as pytest tests and python -m pytest tests. Compiled routing is required unless --allow-python-sidecar is used.

Validate

scaffold-guard validate

Explore

Start with src/atoll/core.py and tests/unit/test_core.py.