Rendered from docs/requirements/0005-a-code-path-names-every-document-that-governs-it.md in the Headwater corpus. Every document on this half of the site is typed by the taxonomy the descriptor names: corpus.json.

A code path names every document that governs it

Context

A person or an agent who is about to change a file asks which documents govern it. governing_docs_for_path answers that question in the query library, and the MCP server gives it to an agent as a tool of the same name.

A governs anchor is a pattern (HW-DR-0074). It can be a single path, a pattern such as src/ingest/**, or a list of members. So one file can match the anchors of more than one document, and each of those documents governs it.

An answer that leaves out one of those documents is the worst failure here. The caller then changes the file and does not read the rule that applied to it.

Requirement

Asked about a code path, the engine names every document that has a governs anchor that matches the path. That includes a match through a pattern and a match through any member of a list.

The answer is the same for every spelling of a path inside the repository. A path with ./, a path with a .. segment, and an absolute path under the root each get the answer of the plain path.

A path that no anchor matches gets an answer that names no document.

A path outside the repository gets one fixed sentence, and no list of documents. #1249 states that sentence.

Verification

HW-AC-0005 is the acceptance criterion. Its method is test, and HW-VER-0004 is the test design that proves it.