Module reference 

Reuse is a link (ADR 0016). A candidate block whose entire content is a single Markdown link to an oath section is a REFERENCE BLOCK: it splices that section’s steps in at its own position instead of being prose.

Everything here is pure text and path arithmetic — no filesystem. The shell reads the documents; references tells it which ones to read, and build_workspace turns the collection into what plan needs.

Structs

OathWorkspace

What plan needs to resolve references: every oath by path, plus which sections a reference block consumes somewhere in the project. A section that is referenced stops being a standalone example, so this is whole-project knowledge — see ADR 0016 on why each runner builds it at its once-per-run discovery pass.

Reference

One resolved reference block: the referenced oath’s path (resolved against the referring doc’s own path), the GFM slug of the heading (empty for a whole-file link), and the link’s visible text.

Functions

build_workspace

Index every oath by path and record every consumed section.

empty_workspace

The workspace with no references at all: what a caller planning a single document in isolation passes.

join_posix

POSIX path arithmetic on oath paths (always ‘/’-separated, relative to the workspace root). The core may not touch the filesystem.

reference_of

The reference a block’s text spells, or None when it is ordinary content.

references

Every reference block in a document, in document order. The shell uses this to walk the closure of documents it must read before planning.

section_candidates

The candidates that make up a section: those whose heading chain contains the slug. A whole-file reference (empty slug) is every candidate in the document. Section membership follows the document outline exactly — a heading’s section runs until the next heading of the same or higher level, which is precisely the range over which it stays on the scope stack.

section_key

A section’s identity across the project.

slugify

GitHub’s heading anchors: inline markup dropped, lowercased, spaces to hyphens, everything else that isn’t a word character or hyphen removed. The same function produces the slug of a heading and normalizes the slug written in a link, so the two meet in the middle.