The graph

Tip
Relations are written once, on the document that makes them. specfold derives the graph on every run, so spec context can tell you which documents govern a file.

Relations

relation	points at	meaning
`rel.governs`	code paths	this document rules that code
`rel.supersedes`	a document	this replaces an older one
`rel.implements`	a document	this carries out a plan or rule
`rel.evidence`	a document	this backs a claim with data
`rel.depends_on`	a document	this needs another to hold

Body references are [[<id>]] or [[<id>#<anchor>]]. Rules L1 and L3 check that they resolve and point at the right types.

A small graph

A plan implements a source of truth, which depends on a decision. Dashed lines are code paths. This block is the output of spec graph --format mermaid on the tutorial repository.

graph LR
  d0["adr:root/20261029190946"]
  d1["plan:shop/20261029190949"]
  d2["sot:shop/cart-totals"]
  d1 -->|implements| d2
  d2 -->|depends_on| d0
  p0[/"services/shop/src/cart"/]
  d0 -.->|governs| p0
  p1[/"services/shop"/]
  d1 -.->|governs| p1
  d2 -.->|governs| p0

Ask the graph

$ spec context services/shop/src/cart/total.rs
$ spec graph impact sot:shop/cart-totals
$ spec graph chain adr:root/20261029190946
$ spec graph consumers org:adr:root/20261030000000

spec context lists the documents to read before changing a path. impact lists what reaches a document, with the relation and distance. chain shows a supersede chain in both directions. consumers lists the documents, in this repository and in each [remotes] directory on disk, whose relations or pins name a document through a remote. In a shared repository, list the consuming repositories as remotes and run it before changing a shared decision; --json feeds a dashboard. Nothing is fetched.

Draw it in a terminal

spec graph prints a tree from the documents nothing points at. A document already shown ends in (*), and --depth N stops N relations away.

$ spec graph
sot:shop/cart-totals  [draft]
├─ depends_on → adr:root/20261029190946  [draft]
│  └─ governs → services/shop/src/cart
└─ governs → services/shop/src/cart

--format box draws layered boxes sized to COLUMNS, and falls back to the tree when the graph is too wide or over 60 documents. --format mermaid and --format dot feed a Markdown renderer or Graphviz. --ascii uses plain lines, chosen automatically outside UTF-8 locales.

Next: how the graph is kept honest, in Checks.