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

MGS7002: dangling doc reference

The knowledge-graph builder scans markdown docs and records an inferred documents edge from a doc page to each MGS#### diagnostic code it mentions in its body. When the mentioned code is a registered diagnostic, the edge links to a real diagnostic node. When it is not - a typo, a code that was removed, or one that was never defined - there is no node to link to, so the builder drops the edge (a dangling edge would corrupt the graph) and tags the doc node with this code and the offending references.

Why

The graph is deterministic and derived: an edge must have both endpoints. A doc that references a code (MGS followed by four digits) that is not registered cannot produce a valid edge, so silently emitting one would leave a target with no node - exactly the kind of torn state the builder guarantees against. Recording the dangling reference on the doc node instead keeps the mention discoverable (the doc clearly meant to cite a code) without inventing a phantom diagnostic.

This is inferred, not extracted: an MGS#### string in prose is a heuristic match, so a false mention (e.g. an example of a hypothetical code) is possible. The code marks the doc for a human to check, not a hard failure.

Resolution

  • If the reference is a typo, fix it to name a registered code; the edge links on the next build.
  • If the code was intentionally removed, update the doc to drop or reword the mention.
  • To find flagged docs: magus query kind:doc, then magus explain the ones whose diagnostic attribute is MGS7002 to see the unknown_codes list.
knowledge-graph diagnosticsLanding page for MGS7xxx diagnostics that flag ambiguities the knowledge-graph extractor hits while building the deterministic graph, such as a buzz import that resolves to no file or a doc that cites an unregistered diagnostic code. magus-docsTraverse magus's own documentation to answer a "how does magus do X / what does Y mean / where is Z documented" question, instead of guessing an answer or a URL. Quick startEverything you need to be productive with magus on one page - install, first target, the output flags, the agent skills and the guard hook - each linking to the page that goes deeper. magus DocumentationThe magus documentation hub covering install, targets, spells, charms, operations, engines, remote caching, MCP, telemetry, and the interactive playground.
MGS7002knowledge graphdocsdiagnosticextractioninferred
Last updated (b022d75e)
Glossary

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.

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.

Knowledge graph

The queryable graph of a workspace's spells, targets, docs, and code relationships; query it with magus query/explain/path. See knowledge.

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.

Conventions

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