Headwater

A documentation governance system.

Status: specification, pre-implementation. Nothing is built yet. The repository holds a specification written to be argued with.

Documentation rots because nothing holds it accountable. Specifications drift from code, rationale evaporates, standards multiply and contradict each other, and the AI assistants now reading that documentation as context inherit every one of those faults — silently, and at scale.

The usual answers are a style guide (unenforced), a wiki (unstructured), or a static-site generator (renders whatever you feed it). None of them can answer “is this corpus still true?”, because none of them know what kind of document anything is.

Headwater's premise: make the structure of the corpus a machine-readable contract, then derive everything else from it — validation, navigation, templates, AI instruction context, publishing, and the evidence that the whole thing is working.

The three commitments

1. Taxonomy is data. What shelves exist, what document kinds live on them, what metadata they carry, and how they may reference each other — all declared in one versioned schema. Customizing the taxonomy never means forking the tooling.
2. The corpus is a graph. Documents are typed nodes and front-matter references are typed edges. Every validation rule is a constraint on that graph, and every derived artifact is a projection of it.
3. AI assistants are readers in their own right, and measured ones. The system probes whether the context it supplies actually changes agent behavior, rather than assuming it does.

Namespace

Emitted artifacts carry the permanent identifier https://w3id.org/headwater/. See the namespace documentation for what resolves there and why it is not this domain.