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

Guard rules

What this workspace enforces. A deny refuses the call and names the replacement; an advise attaches context and blocks nothing.

Every verdict names its rule in brackets (deny [stage-all]: ...), and that name is the entry below. magus describe rules prints the same list.

Refuses

Rule Catches
agent-sign-off an agent stamping a read receipt or closing an attention request, which only a person may do
backtick-substitution a backtick command substitution, which inside double quotes runs a command
brief-command a spawn or continuation brief that teaches a command the guard denies
busy-wait a loop polling for work you started, which announces its own completion
buzz-unbriefed the first Buzz a session authors, by file write or magus buzz -e, before reading the Buzz skill
cache-dir-write a write into this checkout's magus cache dir, which magus alone owns
capture-filter a filter over a run capture or log, which cuts the failure block apart
cd a cd before a magus command, when the project is an argument
claimed-declaration a leased edit landing in a declaration another live job claims (run.go#executeStages)
credential-verb an agent minting, printing, rotating or revoking a credential through the CLI
exit-status-echo a line ending by printing an exit status, which the harness already reports
filter-without-input a filter with no file, pipe or redirect, which reads a stdin nothing feeds
interpreter-rewrite an inline interpreter rewriting a file this tree already carries
merge-side-checkout a checkout of one merge side over a conflicted file, which discards the merge
notes-author an agent authoring a human's note, whose only provenance is who wrote it
output-pipe magus output piped into a filter, when magus projects the record itself
output-redirect magus output redirected to a file, which the run log already holds
process-poll a process table inspected to wait on magus work the lock already reports
push-ungated a push at a commit with no green gate: the person is asked, a leased worker refused
raw-tool a toolchain command a spell already wraps, run outside the cache
scripted-rewrite a scripted substitute-and-write, which cannot tell your symbol from a dependency's
search-translation a text search whose pattern a graph query provably answers with the same entities
sed-in-place sed -i, whose two spellings destroy each other's work across platforms
shared-stash a bare stash push or pop, on a stack every worktree shares
sibling-checkout a magus command relocated into another checkout, judging a tree nobody ships
spawn-unbriefed a subagent spawned before the multi-agent skill loaded
stage-all a whole-tree git add (-A, -u, ., --all, --update), which sweeps in regenerated output
symbol-search a recursive text search for names the graph answers exactly: symbols or diagnostic codes
throwaway-copy a run inside a temp or scratchpad copy, which leaves the real tree unverified
token-state an agent reading or writing the token secrets: the operator token file or the token store
unknown-env a retired or misspelled MAGUS_* variable handed to a command
whole-tree a whole-tree VCS reset, checkout, restore or clean, which cannot be undone
worktree-remove removing a worktree, which may hold another session's uncommitted work

Explains

Rule Catches
chained-run several magus runs chained on one line, where the dependency graph would have run them
checkpoint-state a command reaching for a tree's identity, which a revision alone cannot give
focus a read or write outside the paths the running job declared
gate-repeat the gate run again soon after it passed, repeating work already done
generated-write a hand edit to a declared output, which the next run overwrites
graph-stale a graph read while the index is older than the sources it describes
hook-wiring a write to the host wiring that decides whether these rules run at all
installed-skill a write to an installed skill copy, which re-installing discards
lease-invalid a call naming a lease this workspace's job store does not declare
lease-terminal a call naming a lease whose row has already finished
leased-path a write into paths a running lease owns, by a caller that names no lease
memory-write a write to a memory file, where the memory surface is the way in
new-file a new file in a directory whose naming has settled
new-source-dir a new file that opens a directory, which is a boundary rather than a file
precedent-search a hunt for one distinctive name, which refs answers with verified sites
push-gate a push the run log does not prove ungated, which names the gate and lets it through
regen-source a hand edit to a file a target regenerates
revert-classify a revert that has not classified what it is reverting
scope-drift a write into a project this session has no dependency edge to
skill-source a write to an installed skill copy rather than to its source
source-read an unbounded source read the symbol index has already answered
split-run the same target run again on a different project set, on one line or as a separate call
stage-classify staging without classifying, when generated and source differ
unleased-write a write magus cannot attribute while a fleet is running
guardrulesreference
Last updated (a7c8cace)
Earlier changes on this page (7)

Full history ↗ · Blame source ↗

Glossary

Workspace

The magus root directory that owns a set of projects and shared config; the unit magus operates over. See workspace.

Project

A directory magus recognizes as a unit of work (it has a magusfile); the unit of caching, scheduling, and dependency tracking. See workspace.

Target

A named operation (build, test, ...) you invoke with magus run <target>; it may compose a spell's tool-native operations and depend on other targets. See targets.

Op

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

Spell

A language/runtime adapter (e.g. go, md) that maps generic targets onto a toolchain's real commands. See spells.

Buzz

The language magusfiles are written in (the .buzz engine). See engines.

Cache

The content-addressed store magus consults before running a target, so unchanged work is skipped. See cache.

CI

An ordinary magusfile-defined target you compose yourself with magus\needs - magus does not hardcode its stages. Magus.RunCI treats it specially only in that it strips the rw charm, it is the anchor magus affected ci keys off, and a selected scope with no project declaring it is a load error rather than a silent no-op. See targets.

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.

Session

An agent host's conversation, by the id the host delivers to its hooks. magus never mints one: a record with no session is unattributed, and the OS user it carries says whose account ran it.

Attention request

A durable "an agent is blocked" record, opened when a magus session notify event carries the waiting or permission outcome and held until a person disposes it. magus session attention lists what is open. Nothing closes one on its own - see doctrine.

Job

The unit of delegated work, and one row of the job store: what an orchestrating agent handed out, with its goal, the checkpoint it was cut against, the paths it may write or must not touch, and the one check it runs. A job's holder is either a session, for work an orchestrator handed out, or the server, for its own maintenance. The store records; the agent guard is what reads those facts back when grading a write. See doctrine.

A job is not a run. magus run build web is a run, and no job exists for it. A job causes runs: its check executes as one, and a server job records the invocation of its last one. Jobs are listed with magus ls jobs and in the console's Jobs view; runs are listed in the Runs view.

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.

Lease

The grant a holder takes on a job: the write and read paths that job declared, enforced in the checkout that took it with magus job exec. A job is the piece of work; a lease is permission over it.

Conventions

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