magus v0.4.3 is out. See what's new
¶ View markdown source · ✎ Suggest an edit
1 min read

Measured, not asserted

A design reading well proves less than it used to, so a claim needs an artifact someone else can check: a benchmark committed with the hardware, the date and the competing tool versions; a run journal; a count over transcripts with the recipe to reproduce it. Weigh anything without one as experience, and say so in the sentence that makes the claim.

Measurement cuts both ways, and the useful half is the one that says no. A conformance check that fires on four deliberate designs out of four is noise; an advisory that fires on 0.8% of edits, all of them matcher artifacts, is a toll. The rows in A record of refusals that record a measurement killing an idea somebody wanted are the reason the rest of that list is worth anything.

A measurement also says where the tool falls short. The same journals that show what the cache saved show what it did not, and a page that only publishes the good half is marketing.

Enforced by

  • Benchmarks publishes every run beside the environment that produced it, controls first.
  • A conformance threshold is a relative bound with a committed ratchet (hack/policy/conformance.jsonl), so a rule's floor is a number in the tree.
  • A record of refusals names the measurement and its date beside each refusal.

Good

A refusal row that carries its measurement:

an advisory when an agent edits a file it never looked up | not built: 0.8% of 3,560
first edits were never anchored, and all 27 cases read by hand were matcher artifacts

Bad

The graph makes agents 3x faster.

No run, no control, no date, no recipe. Nobody can check it, and it outlives whatever it was ever true of.

See also

designprincipleevidence
Last updated (2df714e8)
Glossary

Cache

The content-addressed store magus consults before running a target, so unchanged work is skipped. Cache in full.

CI

An ordinary target you compose yourself with ctx.needs; magus does not hardcode its stages. It is the anchor magus affected ci keys off, and ci strips the rw charm. CI in full.

Agent

A model working through an agent host such as Claude Code, Codex, Cursor or OpenCode. magus treats an agent as one more caller of its CLI, MCP tools and console, held to the same checks as a person. Agent in full.

Tool

An action a model can call through its host: a name, a description, a typed input and a result. magus serves its tools over MCP, each a read of the workspace model or a run of the CLI it already has. Tool in full.

Run

One target executing under one magus invocation, such as magus run test web or magus affected ci. A run keeps its captured output behind an output reference. Every magus run is a run whether or not any job asked for it; see Job for how the two relate. Run in full.

Advisor

One read-only check from the advice suite: it reads the changeset through magus and writes one titled section of findings. The same advisors run as a pull request comment in CI and inside magus diff --impact locally. Advisor in full.

Conventions

This page uses none of the site's convention markers. The full set is on the conventions page.