Log in
docs/adr/0001-stdlib-only-harness.md 27 lines · 1.0 KB

ADR-0001: The harness is dependency-free Python stdlib

  • Status: accepted
  • Date: 2026-06-10

Context

The benchmark must run identically on developer laptops, CI runners, and ephemeral cloud machines, often driven by coding agents that cannot be trusted to set up virtualenvs correctly. Every dependency is a source of version skew that can silently change measurements.

Decision

Harness code under scripts/ uses only the Python 3.9+ standard library. Optional enhancers (tiktoken for exact token counts, pyyaml for spec validation) are detected at runtime and never required. Where a format parser is needed (TOML subjects config, mount-spec YAML subset), we ship a minimal parser for exactly the shape we write.

Consequences

  • python3 scripts/<lane>.py works on a fresh machine with the VCS binaries installed and nothing else.
  • Tests use unittest, not pytest.
  • Minimal parsers must stay minimal: if a config outgrows the subset parser, simplify the config rather than growing the parser.