Log in
docs/adr/0006-git-baseline-books.md 33 lines · 1.3 KB

ADR-0006: Git Baseline Books are committed summaries

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

Context

ADR-0003 keeps raw result JSONL and run artifacts out of the repository. That remains correct: raw rows are large, runner-specific, and belong in external storage. The benchmark also needs a stable TDD target for "beat Git" work. A developer or agent should be able to compare a candidate run against a pinned Git reference without guessing which historical JSONL object is canonical.

Decision

Curated Git Baseline Books are committed under baselines/git/<book_id>/:

  • manifest.json records suite revision, runner class, Git binary SHA256, fixture/config/calibration versions, noise floor, and raw-row storage keys.
  • book.json records per-cell summary statistics and confidence intervals.
  • book.md is the human-readable rendering.

The raw JSONL remains external and is linked by hash/key from the manifest. Books are immutable once published. baselines/git/CURRENT may move to name the active book for a runner class.

Consequences

  • This is an explicit carve-out from ADR-0003 for compact, curated summaries only.
  • A scorecard can run from a fresh clone without fetching every historical row.
  • Updating a Git baseline is a publication event: create a new book id rather than mutating an old book.