debrief

The evidence MCP: answers agent questions from receipts — what ggufbench measured, and where the last buildwright run broke — and proposes role changes as text. It never writes.

Status: scaffolding. The harness is installed and the parent feature is pending — the spec (harness/specs/debrief/) is not written yet, so the tool list below is the plan, not the product.

The idea

• ggufbench owns the catalog: what a model measured, under which task signature, and why rows were excluded.
• buildwright owns the episode: one run, its gates, its failures.
• debrief is the reader. One query surface, one shared finding type, and a proposal that cites both. Two ports that answer different questions:

Product rules (the gates that matter in code)

1. debrief never writes. Every tool is read-only or returns a proposal as text. No tool touches .env, BW_ROLE_*, models.yaml, or any other file.
2. Proposals target roles, not the registry. A proposed change is a BW_ROLE_<ROLE> diff. models.yaml is the registry of what exists — not debrief's to edit.
3. bench and run answer from their own source. run may cite bench findings; bench never reads runs.
4. Rows never cross a task signature. Incomparable rows are refused with a reason — never averaged.

The gates (process)

The repo runs the harness SDD workflow in hybrid mode: one in-session agent plays the roles, the human gates stay mandatory. Architecture is hexagonal (docs/architecture.md); features are cut into vertical slices (docs/slicing-protocol.md) — S1 bench_query → S2 run_inspect → S3 role_propose, each demoable end-to-end.

Two gates are non-negotiable and human: the Spec Gate and the Completion Gate. The gauntlet filters what reaches them; it never replaces them.

Development

uv sync
uv run pytest tests

Requires Python ≥ 3.14 (uv).

Repository map

See AGENTS.md — it is the navigation map for agents (and humans). Architecture: docs/architecture.md. Decisions worth remembering: harness/decisions/.