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

A refusal carries its reason

A refusal names the mechanism and a next step. Diagnostics are coded and documented so you can look one up. A stale binary can surface as a typo and a missing tool as a lint finding; where magus can tell the difference, the message says what is happening underneath. The same rule reaches workflow refusals: notes edit declines to rewrite a note's anchors from a pipe, and the error says why anchors are not pipeable and what to do instead.

A denial that says no and nothing else sends you around the tool, and the workaround runs outside the cache and the sandbox, where magus can no longer account for the work. An error that leaves you with no next step is a design bug; file it as one.

Enforced by

Good

A refusal from this repository's guard, naming why and what to run:

`sed -i` reads differently on GNU and macOS; use your editor tool.
Renaming a symbol from a script? `./magus buzz hack/dev/rename-symbol.buzz -- --symbol <old> --to <new>`

Bad

error: operation not permitted

It names no rule and no next step, so the caller works around the tool, and the workaround runs where magus can no longer account for it.

See also

JudgmentPages in this section. Inform people, contain the engineGuardrails live in the engine (the sandbox and the cache), not in a schema that predicts you; magus is strict about what it tells a person and permissive about what it lets them do. ScopeThe claim magus is built on: that a correct incremental build already requires a precise model of your repo, and everything else is a read of it. Includes the test for what belongs, the boundaries, and where the claim is strained. ChangelogEvery change to magus, newest first, in Keep a Changelog format, starting with the unreleased entries. Generated from changes/unreleased/ and releases/*.yaml.
designjudgmentdiagnostics
Last updated (2df714e8)
Glossary

Op

A single tool-native command a target composes (long form: operation); the middle of the work hierarchy (Spell to Op to Target). Op in full.

Buzz

The language magusfiles are written in (the .buzz engine). Buzz in full.

Cache

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

Sandbox

The restricted filesystem and environment a target runs in, so builds stay reproducible and side-effect-free. Sandbox 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.

Diagnostic code

A stable MGSxxxx identifier attached to a magus warning or error, so it can be referenced and looked up; some are guardrails (see wards), others hard errors. Diagnostic code 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.

Conventions

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