Doctrine

Scope records what belongs in the tool. This page records how the tool is allowed to behave: the principles it is built by, the standard any addition is measured against, and the line between decisions magus automates and decisions it hands to you. Each entry names the mechanism that enforces it and the failure it prevents; check them against the tool you are running. An entry whose mechanism does not exist yet is listed at the bottom as a debt, because a rule that lives only in prose is a rule with roughly even odds.

Principles

Unix survives at the verb, not the binary

One tool that does one thing extremely well does not survive contact with a monorepo, and magus does not claim the lineage: a monorepo build tool has to understand several languages, every project in the tree, caching, scheduling, and what a change reaches. That is already many things. What survives the translation is the discipline, relocated to the verb. Each verb answers one question, deterministically, from declared sources, and stops. Output reads at a terminal and parses in a pipe (-o name, -o json, -o template=; the pipe is for people, and the agent guard routes an agent to -o instead, because a pipe replaces the exit status and a failing gate then reads as 0). A non-zero exit means what it has meant for fifty years. Every surface degrades to plain text when there is no terminal to draw on, and the pinned band never takes the screen, the alternate buffer, or your scrollback. Composition happens where a monorepo needs it - in the graph, through ctx.needs - not by pretending the binary can be smaller than the problem.

The scope test governs what a verb may be, and the one-vocabulary rule - target, spell, charm, op, each named once and reused everywhere - keeps the surface predictable. That prevents the failure in both directions: claiming a minimalism the tool cannot carry, and the house dialect with no rule you can hold in your head, the one that makes users look things up forever and then teaches their agents the same confusion.

Capability is not a reason

Building the wrong thing got cheap. Coherent, well-structured, completely misconceived work can be generated in minutes, so a design reading well proves less than it used to, and someone still has to say no to work that would otherwise ship. The default answer to a new capability is no, and the burden of proof is a failure removed, never a preference enabled. The version window needed four dead designs before one passed that bar; the knobs rule is the same principle applied to options.

The mechanism is the scope test, applied in review by reading the diff for what the tool had to learn. It prevents the accretion this project was a reaction to - each addition defending itself, nobody removing anything - now accelerated, because writing the unnecessary thing costs nearly nothing while maintaining it costs what it always did.

Optimize the loop that verifies, never the loop that generates

Producing code was never the bottleneck. Reviewing it and trusting it were, and both got harder as generating got cheap. So every mechanism here attacks the verify side: the cache makes re-checking free, affected makes the check minimal, the drift gate makes generated output self-verifying, the explain lenses make verdicts inspectable, describe file makes a diff triageable. Nothing in magus exists to make producing code faster. That is a commitment, not a gap.

The test for a proposed feature is whose loop it accelerates. A pitch of "produce more, faster" fails by construction; "know sooner, trust cheaper" is at least aimed at the right loop. This prevents magus from becoming a tool whose product is throughput - volume is the one metric that gets easier to move every year and proves less every year, and a build tool that helps ship more unverified work faster has joined the problem it was built against.

The horizon for that test is years. A tool that generates on your behalf compounds dependence: what its operator can ship drifts past what they can judge, and the gap is the crutch. A tool that verifies compounds judgment, one answered question at a time. Automation you can interrogate holds the enforcement half - helpful, never so helpful that the operator stops learning.

A cache is an accelerator, never a dependency

Every cache magus has - the local one, the remote one shared through CI, a published knowledge graph pulled as an OCI artifact - skips work that the machine in front of you could do itself. That is the whole contract. Delete the cache directory, revoke the registry credential, unplug the network, and a clean clone still builds, still gates, still answers. It is slower. It is not broken.

The line to hold: a cache may shorten a derivation, never be the only copy of one. The moment a clean clone cannot proceed without fetching something, the artifact has stopped being a cache and become an undeclared build input, and the questions that follow are the ones no cache should raise. Who can serve it. What happens when they do not. Whether the bytes are the ones the source would have produced, or the ones somebody uploaded. A tool that installs through none of the toolchains it drives, for reasons Scope states as a rule, does not get to quietly depend on a registry for its own derived state either.

This is why the remote cache is verified by a trust set rather than trusted for being reachable, why an unverifiable artifact is a miss rather than a warning, and why magus graph pull is an optimization over magus graph build rather than a step before it. It is also the test for any future store: if switching it off changes an answer rather than a duration, it was never a cache.

The failure it prevents is quiet. A cache that becomes load-bearing does not announce the change; it works, for months, until someone clones fresh on a plane and discovers the build was distributed all along.

Human-first is the AI integration

magus was built for humans, and agents drive it well anyway, because an interface legible to a person is legible to anything. That ordering is the design, and the reason underneath it is structural: models learned to use tools from decades of humans using tools, so a tool that honors the conventions humans settled - exit codes, a working directory that means what it means everywhere, a path as a project's name, plain text - inherits agent competence for free. A tool that invents its own dialect fails both audiences, then watches the models learn its workarounds forever. Buzz is the evidence we have: a language with close to no training data produces better agent output than the most-trained languages on earth, with explicitness the only variable in sight. Weigh that as experience rather than benchmark; it is still the strongest evidence on this page.

The mechanism is an ordering rule with one worked example: no surface is designed for an agent first. The agents key in affected ci --plan is the one agent-specific field in an otherwise human-first surface - the skill-routing hint sits quarantined inside it, so everything around it reads as what it is, ordinary build metadata a person wanted first. The one deliberate exception is the job store, an agent-to-agent declaration under Agents propose, humans dispose: it is written by agents through MCP and read by people at magus ls jobs, so the asymmetry is in who ordinarily authors it, not in who may see or write it. This prevents the bolted-on AI integration, papering over a tool people already struggle with, and the quiet inversion where a person becomes the secondary user of their own build tool.

The floor under the ordering rule is an absent seam: magus never calls a model (Scope records the missing adapter as deliberate). The closest feature, magus diff --prompt, prints the context magus holds for you to paste into your own model, and never a drafted review. Every capability on this surface is a person's to run with no agent anywhere in the loop; the agent surface is additive, never load-bearing. The installed skills are gitignored renderings of the binary, so nothing in CI can drift-gate them; magus doctor's agent-skills check is what observes staleness, per workspace (Scope). A workspace that goes a day, or a Friday, without an agent loses nothing but speed.

Verdicts are provenance-blind; disposition is not

A verdict - the cache saying a replay is honest, the drift gate saying generated output matches source, a diagnostic, a CI result - judges the work. No verdict conditions on who or what produced the change: cache keys hash content, the drift gate compares bytes, diagnostics read the tree. Whether a change was typed by hand or generated is invisible to every gate, on purpose, because good software is the only defensible standard at the tool layer, and a bar that moves with the byline is theater in both directions - extra suspicion for one author, unearned trust for another.

Disposition is the opposite case. Accepting a proposal, sending a review, landing a change: these are accountability, and accountability needs a true name. That is why authorship is stamped from the transport a write arrived on, never from what the writer claims about itself - the mechanism described under Agents propose, humans dispose. The blindness half is structural today and stated here so that a proposal to break it, a gate keyed on how code was written, has to argue with this page first.

Exactly one code path grades a write by who is acting, and naming it is what keeps the rule checkable. gradeLeasedWrite reads the lease ledger to decide whether a worker is editing outside the paths its lease declared. That is a concurrency-ownership question on the guard surface - who owns this file right now - rather than a judgment about the work, and it reaches no cache key, no drift comparison, and no diagnostic. Its uncertainties - no ledger, no live lease, a file that will not parse - fail open with at most an advisory.

Worth cloning

Assume magus can be reproduced. A model given the binary can recover the architecture; given the docs, it can recover the rest, and the cost of doing so falls every year. So no part of this project's value is allowed to rest on that being hard. What cannot be recovered from the artifact is the judgment that produced it: which capabilities were refused and why, what was measured before a mechanism shipped, where the line between the tool and the person was drawn and what it cost to hold. That record is the product, and it is published on purpose. A clone that carries it improves the lives of the people who run it, and a clone that drops it is a different tool wearing the name.

The test for what to build is therefore whether it is better when copied. A vocabulary that another build tool adopts makes every agent better at both. A guard rule that another harness lifts protects someone this project will never meet. A measurement that kills a feature here saves the same feature elsewhere. Each of those returns more to this project when it spreads than it would have kept by staying scarce, because the thing magus optimizes for, people who can still fix their own software, is not a market to corner.

The mechanisms are the license and the absences. GPL-3.0 makes the copy legal and keeps the copy's improvements public. Scope records that no account, paid tier, or capability behind either exists, so there is nothing a clone would have to route around. The refusals ledger and the measurements behind each rule on this page are in the tree, not in anyone's head. This prevents the failure that makes the assumption above dangerous: taking on debt to build a moat that will not exist, and then measuring the project by what it managed to keep from people instead of by what it left them able to do.

The standard

Adapted from Wendell Berry's nine standards for adopting a new tool ("Why I Am Not Going to Buy a Computer", 1987). His subject was a farm; the criteria survive the distance because they are about what a tool owes the person who takes it up. Held against magus in both directions - what magus asks of itself before adding anything, and what you should ask of magus before adopting it:

1. Cheaper than what it replaces. Total cost: install, learning, upkeep. One binary, no account, nothing to upsell, no toolchain underneath it to break. The honest half: the learning cost is charged up front, and the claim is cheaper over a year, not cheaper in week one.
2. At least as small in scale. The surface may not outgrow what one person can hold. Enforced today by judgment alone; the ledger that would measure it is a debt, below.
3. Clearly and demonstrably better. A claim of better needs an artifact someone else can check: the benchmark results, committed with the hardware, the date, and the exact competing tool versions they were taken on; terminal recordings that are captured bytes rather than mockups; the drift gate. The claim that querying the graph beats grepping is argued from mechanism and not yet measured; weigh it accordingly.
4. Uses less energy. affected and the cache are this criterion implemented: run only what a change reaches, never do the same work twice. The savings are real and currently invisible; a debt, below.
5. Powered by what the work already produces. Berry said the body's own energy. Here it is the scope test verbatim: every capability reads the model that correctness already forced the build to hold, and the one exception, the release registry, is named there.
6. Repairable by its user. Refusals carry a next step, every diagnostic code has a page, the host wiring is a template you own, no generated code sits between you and a running build, and the guard fails open with a notice rather than failing silent. The systematic version is missing; a debt, below.
7. Repairable near home. The cache is a plain store on your disk, the console is loopback-locked, no capability requires a hosted service, the server accelerates and never gates. The exceptions run on infrastructure we operate; Scope names them.
8. From a shop that will take it back. One maintainer, said plainly, and the mitigations are structural rather than social: a sealed engine kept small, documentation written before announcement, GPLv3 so the tool stays repairable in common if the shop ever closes. Choosing Buzz for its maintainers was this criterion applied to a dependency before we had read it stated.
9. Disrupts nothing good that already exists. The terminal's decades of contract stay intact: scrollback, selection, the working directory, plain text, your toolchain visible and yours. The console is where this is under active tension, and it ships under a rule: what does not give genuine value over the good thing that already exists should not ship.

Judgment

The entries above say how the tool is built. The rest of the page records when magus automates a decision and when it hands the decision to you.

Agents propose, humans dispose

An agent surface can suggest work; it cannot accept it. magus records authorship from the surface that performed the write, so a change carries the origin the channel delivered (the OS account, the entry point, the credential or host) no matter what the writer reports about itself. Interrupting a person costs attention, and the suggestion operation reflects that: it requires a stated reason before the proposal reaches anyone. The job store is ordinarily written by agents, unlike the attention events notify raises, because an attention event is addressed to a person while a job is an agent-to-agent declaration read back by the guard and the console. A person still has a full door onto it: magus job forks, takes and returns a job, and magus ls jobs reads the plan back. What keeps the book honest is one author per row, enforced by the store rather than by a closed CLI.

Automated review is wrong at a steady rate, and wrong in a characteristic way: the confident finding that "fixes" behavior somebody chose on purpose. The person deciding whether a proposal lands is the one who catches those findings. If magus applied them itself, they would ship unexamined.

The host wiring is yours

magus owns the guard rules and the verdict. It does not own an integration with your agent host. The rules come from one binary and are identical everywhere; the part that knows your host - which event field carries the command, which reply channel reaches the model, what happens when the binary cannot be found - is a template you copy and edit. Adding a host is your change, not a magus release.

The contract is small enough to hold in your head. magus session hook takes the thing to judge on stdin, either plain text or a payload keyed by FIELD (tool_input.command, file_path, prompt), never by a host name or a tool name. -o template= renders the verdict into whatever shape the host's reply takes. TestNoHostSpecificBehaviorInCode fails the build when a host's NAME appears in code anywhere but a path on disk, and the magus-guard-coverage: line each template carries feeds a parity gate that fails when a host was never asked about a decision the contract grew.

A branch keyed on a host's tool vocabulary rather than its name - a switch over Read and Bash - is a per-host branch in everything but spelling, and the name test cannot see it. TestGuardDoesNotBranchOnHostToolVocabulary is the second layer: it fails the build when a host's word for a tool appears as a string literal in guard code at all, so a lookup table is no cheaper than a switch. The activity-event tool labels are magus's own vocabulary for that reason, chosen by which flag the wrapper passed.

A layer that made every host work with no friction is what is being traded away here, and it is worth being plain about the trade. Agent hosts change their event shapes and hook names on their own schedule. A workspace whose integration lives inside magus waits for a magus release to get unblocked; a workspace that owns fifteen lines of shell edits them that afternoon. The cost is charged up front and on purpose: you read your host's hook documentation once, and there is no zero-configuration path.

The second cost of such a layer is the one nobody sees until it matters. A guard you did not wire is a guard whose failure mode you do not know, and this one fails OPEN by design, so a hook that quietly stopped judging looks exactly like a session with nothing to deny. So a shipped template announces its fail-open arms rather than exiting quietly, and TestFailOpenArmsAnnounceThemselves fails the build when one stops. One template is exempt, and the test declares it rather than leaving it to be discovered: the path template stays silent. An empty response on that surface already means allow, a notice on every file edit was judged the worse noise, and hearing about it there is opt-in. Whoever runs the guard should be able to read what it does and repair it without us.

The same holds for credentials: the guard is a seatbelt, not a boundary against a process running as you, which can read any file magus can. So the guard refuses what an agent should not do, and magus separately enforces every layer it can prove, a planted token file that cannot grant more than a mint, a token that never mints a wider one, rather than claiming a sandbox it does not have (Tokens and grants).

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 doctrine bug; file it as one.

Misconfiguration is an error, never a warning

A setting magus cannot honor fails the command that read it. It is not logged and stepped over, not repaired with a default, not carried as a warning nobody reads in a CI log that scrolled past an hour ago.

The reason is what a warning actually communicates. You wrote the setting, so you believe it is in effect; a warning leaves that belief standing while the behavior underneath it is something else. Every subsequent decision rests on a premise the tool already knew was false, and the failure surfaces somewhere far away, as something else, long after the edit that caused it. A tool that knows a value is wrong and proceeds anyway has chosen to be misleading.

So the test for any warning is one question: is the value honored? If it is not, the warning is a bug in disguise, and the fix is to fail. If it is, say nothing, because a warning about something that works is noise that teaches people to skim past the warnings that matter.

The corollary binds the other direction: a knob magus accepts is a knob magus must obey. A field that reads as a retention window while the code enforces a fixed cap, or a flag documented as repeatable that silently keeps the last value, is the same defect as the ignored setting. It just fails later, and reads as a lie rather than an oversight.

Told, never guessed

magus does not guess where it runs in order to change what it does. It does not read CI, GITHUB_ACTIONS or GITLAB_CI, probe for a container, or work out which agent host is calling, and then pick a default, a result, or which provider or feature is on. When a caller needs different behavior, the caller asks for it: a flag, a charm, a key in magus.yaml, or a variable the workflow sets on purpose. The same command does the same work on a laptop, on a runner and inside an agent's shell.

The owner's words, when this was written down: "We should never be doing environment sniffing, ever. Thinking that we're smarter than the developer, or trying to be too clever, is incredibly dangerous."

The danger is the same one the previous entry names, arriving from the other side. A guess is a setting nobody wrote. It cannot be read in the file the reader is already looking at, it cannot be turned off without first learning it exists, and it is wrong exactly where the environment differs from the one its author pictured: a self-hosted runner that looks hosted, a laptop with CI=true exported by a test harness, an agent host that happens to share a field name with another. A command that passed locally and failed in CI because magus noticed it was in CI is the worst kind of red, because the difference is invisible in both places.

Two things are not guessing. The first is adapting to the terminal in front of the person: whether a stream is a terminal, what kind and how big, whether it is reached over ssh, and which window a once-only notice belongs to. That decides how magus talks to them (color, links, hover, which prompt it can show), never what work it does. The second is reading the input a caller actually sent: a flag, an argument, the event a hook was handed. NO_COLOR belongs with them: a person set it to say what they want.

An agent host is a caller like any other, so it says who it is. The hook configuration magus agent harness apply writes names the host explicitly, and a hook invoked without that name is refused rather than defaulted to one host.

TestNoEnvironmentSniffing in conventions_test.go fails the build when code reads a CI, hosting or agent-host variable outside a short list of inputs read after the caller chose them, and the failure says to take a flag instead.

Automation you can interrogate

Each automated verdict has a lens that shows its inputs. affected --explain says why a project is in the affected set. describe target --cache --inputs says what hashed into a cache key. describe file says whether a file is generated and by what. explain gives a graph node's provenance and edges. New behavior ships with its lens in the same change: an action magus cannot account for is a defect in the same class as a wrong answer.

The lens rule has a second half, and it is criterion 6 pointed at the tool itself: a step magus runs on your behalf should be expressible as the toolchain invocation it performed, so a year of running magus leaves you knowing more about go build and your own repository, not less. A spell wraps a tool without hiding it, and there is no shortcut in there where knowing what your toolchain does stops being your job. Helpful, but never so helpful that nobody using the tool learns anything from it.

Manual on purpose

magus could automate each row below, and does not.

All four would be cheap to build, and cheap is not the test. The test for any future row: does automating the step remove a repetition, or remove a rep? A repetition - the same build run again for no new information - is the tool's to eat, and the cache exists to eat it. A rep - reading the failure, deciding what it means, choosing what lands - is where judgment forms, and a workflow optimized until its operator no longer forms the judgment it depends on has automated the wrong half. Each row above removes the person at the point where the mechanism needs their judgment, so each stays out.

Sending a review is the newest of them and the one with the most surface to give away, so its refusals are worth naming: no review command carries a --publish flag, a self-review is always a comment rather than an approval, and authorship is stamped from the transport a write arrived on rather than from what the writer claims. A batch waits for a person because publishing is one outward-facing act; splitting it into a call per remark would turn the act that needs confirming into a series of small ones nobody confirms.

Corrective competence

The skill this page protects is narrow: your ability to fix the thing yourself when the agent is wrong, or gone. Not speed, and not thinking in general.

Two studies set the target. Bastani et al. measured nearly a thousand high school students with a tutor that handed over answers: 48% better on practice while it was available and 17% worse on the exam once it was taken away, against 127% better and no measurable residual harm for a version prompted to give hints instead.¹ Sankaranarayanan found that 77% of novice programmers given unrestricted AI failed a 30-minute maintenance task once the assistant was withdrawn, against 39% of a group whose tool made them explain generated code's causal logic before it would integrate it. The two groups produced equally functional work; the explaining group took about a third longer to do it.²

The mechanisms are already on this page. Notes are human-authored by construction. --ack refuses without a terminal, agent hosts are denied it outright, and the count is shown to nobody but the reader. The guard advises where advice will do and denies only what cannot be undone. magus never calls a model, which is what makes the Friday above an option rather than a slogan.

This repository is built with agents at scale: 113,430 agent-run shell commands in twenty-one days. Our own oversight lapsed too. In 22 of 203 recent sessions the guard was not running, and those sessions carried 17% of all commands. The only reason that number exists is that we went looking for it.³ Whether the surface earns its cost is measured the same way rather than asserted: Benchmarks publishes every run beside the environment that produced it, controls first.

Where this is strained

Friction placed wrong is bureaucracy. A refusal that teaches and one that nags differ in nothing but their message text, and message text rots like any other prose; the doctrine holds while error messages get the same care as code.

The explain lenses cover verdicts magus computes. magus captures and replays the output of the tools a target drives, but it cannot make a third-party tool's reasoning inspectable; the lens stops at the tool boundary.

The host boundary still has costs, but the binary no longer owns host location lists. A harness descriptor declares a configuration path, native event matchers, response template, and skill locations; magus doctor verifies that contract as data, and agent install follows its declared skill paths. A host neither one names can still work through a portable adapter, while a new native host can add a collaborator without a Magus release. The envelope field names remain host-shaped, so a host that spells them differently reshapes its payload before piping it. And the OpenCode plugin carries a type-check and tests because it is real TypeScript, which is more upkeep than a shell template and more than an example should need.

Four rules on this page live only in prose today, and by this page's own standard that makes each a debt. Every one is a read of what magus already records, so each passes the scope test; none is built:

• The surface ledger (criterion 2): a generated, committed inventory of verbs, flags, config keys, and diagnostic codes, regenerated by generate so the drift gate lands any growth in the diff of the change that caused it, where the person who can say no is already looking. Not a cap - a number nobody can fail to notice.
• The savings lens (criterion 4): what the cache and the affected set actually bought - runs replayed against runs executed, wall time avoided - as arithmetic over run records that already exist, interrogable like any other verdict. Until it exists, "the cache is worth its complexity" is taken on trust, which is the one way this tool asks not to be taken.
• The departure test (criterion 1): Scope claims that deleting everything magus wrote leaves magus run build working, and admits the claim is thinner than it sounds. An audit job that strips those artifacts in a throwaway worktree and builds would make the exit guarantee self-verifying instead of asserted.
• When it breaks (criterion 6): the diagnostics reference covers coded refusals; the failures that never raise a code - a server that did not bind, a watcher gone stale, a cache entry that will not replay - are documented where someone thought to write them down and absent where nobody did. The systematic version is a failure-modes section per concept page, enforced the way this repository already enforces document shape.

The line between automated and manual moves as a mechanism earns confidence. To move a row out of the table above, or a debt off this list, edit this page in the same commit that changes the behavior.

A record of refusals

The decision to build and the decision to stop both stay with a person; what the tool owes them is a record that makes each one visible and cheap to revisit. Below is that record: capabilities magus could have had and does not, or had and removed, with what decided each and where to check it.

The rows that record a measurement killing an idea somebody wanted are the only reason the rest of the list is worth anything. A ledger of things nobody was going to build proves nothing.