Rendered from docs/spec/README.md in the Headwater corpus. Every document on this half of the site is typed by the taxonomy the descriptor names: corpus.json.

The specification series

The documents on this shelf, in the reading order this corpus derives.

  • Vision and scope — What Headwater is for, the three qualities it aims at, the eleven design principles, and what it refuses to build.
  • Conceptual model — The vocabulary that the rest of the specification uses, from corpus and shelf to warrant, projection, and the TBox and ABox split.
  • The taxonomy model — The central design, which declares kinds, facets, relations, regimes, the immutable core, and customization by overlay.
  • Authoring and lifecycle — How a document starts, declares itself in front matter, records its provenance, and dies without loss of its lineage.
  • Assurance model — The assurance model, which holds the control postures, obligations, coverage without silent passes, and the places where efficacy is unmeasured.
  • AI integration — How the corpus serves an agent at four moments, and how a probe measures whether any of it works.
  • Engine architecture — One parse, one typed graph, and many consumers, with the pipeline, the library boundary, and the performance targets.
  • Distribution and federation — How a publisher ships a taxonomy, how a consumer overlays it, and what the invariant core requires of the result.
  • Design departures — The ideas that this design adopts, and the eight recurrent failure modes of documentation tooling that it designs against.
  • The decision register — An index of the twenty-one design decisions and the ones that the build raised. For each one, it names where the record lives and the evidence that closed it.
  • Open obligations — The work that the closed decisions left behind, which is unmeasured claims, items that wait on an adopter, and unblocked design work.
  • Open questions, closed and redirected (superseded) — One heading for each document on the decisions shelf, so that a citation naming one of them resolves in this file.
  • The check layer — What a check is, how a scope constrains it, where it comes from, and what the check layer owes the engine.
  • The recorder contract — Everything an external recorder writes into a transcript, and the closed key sets that refuse a file. This part also names the one member of the run identity this engine compares, and the period a result stays citable. (asserted, and no human has accepted it)
  • Harness support — The eleven capabilities a harness supplies at the four moments, stated once for every harness, and the recorded support of Claude Code, GitHub Copilot and OpenAI Codex.
  • Glossary — One line for every named concept in the specification, with a link to the section that defines it.