Proposals

An improvement proposal is EvalBook's statement of a problem it found, a hypothesis, how to reproduce it, the reports it was drawn from, and the limits within which a fix may be attempted. It is the one thing EvalBook hands to CodeBook for work. EvalBook does not fix anything itself; it measures, proposes, and later measures what became of the proposal.

Status (25 October 2026). The improvement component is an empty shell in the application today (one model, no routes, no pages); requirements EV-041 to EV-044, EV-046 and EV-047 are not started in the requirements ledger. This page describes the contract the component is being built to, and nothing on it is available yet.

The proposal body

The peer protocol fixes the body CodeBook receives:

{ "proposal": {
    "id": 118, "title": "…", "problem": "…", "hypothesis": "…",
    "failure_cluster_id": 52, "source_report_ids": [901, 902],
    "subject": { "repository_full_name": "acme/api", "commit_sha": "…" },
    "workflow_id": 9,
    "allowed_paths": ["src/**"], "protected_paths": ["tests/acceptance/**", ".evalbook/**"],
    "max_attempts": 3, "deadline": "2026-10-16T00:00:00Z",
    "budget": { "currency": "USD", "max_amount": "20.00" },
    "reproduction": "…", "url": "…" } }

• Problem, hypothesis, reproduction: the words a person or the investigation assistant wrote, from an investigation.
• Evidence: the failure cluster and the reports the proposal was drawn from, by id. CodeBook can fetch a report by id over the peer channel and recompute its digest.
• Subject: the repository and commit the failure was observed on.
• Workflow: which CodeBook workflow the card lands in.
• Bound: max_attempts, deadline and budget. CodeBook enforces the bound through its run limits, not by asking a model; a run past it does not start, and an unpriced model counts as unmeasured, not as free.
• Paths: allowed_paths and protected_paths. The protected paths are a refusal list that every repository-writing tool in CodeBook checks before anything reaches the host; a refused write is recorded on the run. Acceptance tests and EvalBook's own configuration are the natural members of that list.
• URL: the proposal's page in EvalBook, for people; never authority.

The values in the example are the contract's illustration, not defaults.

Who may write and dispatch

proposal.write (held by the experiment runner on top of viewer reads) writes a proposal. proposal.dispatch (held by the release admin) sends it to CodeBook. The two are separated duties: the person who writes a proposal does not thereby gain the right to dispatch it. See roles and access. Dispatch itself, and what comes back, is described under remediation.

Events EvalBook emits

Through its outbox EvalBook delivers to each linked peer proposal.created and proposal.updated, keyed proposal.<created|updated>:<id>:<revision>, with body { proposal: { id, state, … } } and the link the event travels on. Deliveries are signed, keyed, retried with backoff for 17 attempts and then marked failed and visible. A peer that does not act on an event acknowledges it and records it as ignored. See peer links.

What CodeBook does with it

CodeBook creates one card per proposal id, named from the proposal, in the first station of the named workflow; a duplicate dispatch answers the same card. It records the protected paths as a refusal list, enforces the bound through run limits, and reports progress back as improvement.updated with one of the states queued, in_progress, in_review, blocked, done, dropped, reopened. A higher revision supersedes a lower one; an older revision arriving late is recorded and ignored. CodeBook's own account of this is at https://codebook.work/docs/integrations/linked-products, and the link that authorizes it is described under CodeBook. Work on a card may itself run under MadeBook governance on the CodeBook side; EvalBook never authorizes that work.

What a proposal counts as

For impact, a proposal is a work unit evalbook:proposal:<id> of work type improvement_proposal. The impact interface recordProposalState maps proposal states onto the event vocabulary: dispatched and started to work_item_started, completed to work_item_completed, accepted and merged to work_item_accepted, reopened to work_item_reopened, rejected and cancelled to work_item_cancelled, each keyed by proposal, state and revision. A completion is self-declared done, not acceptance; acceptance is a merge or an explicit acceptance, and what happens after deployment is told by CodeBook's outcome events.

Optimization proposals

The architecture names a second purpose for model calls, optimization, for proposals that change EvalBook's own configuration rather than customer code. Such a proposal never activates anything by itself: a suite, scorer or judge version becomes active only through the governed path described under release channels.