Rendered from docs/obligations/0104-a-governs-edge-reaches-the-path-it-names-and-nothing.md in the Headwater corpus. Every document on this half of the site is typed by the taxonomy the descriptor names: corpus.json.

A governs edge reaches the path it names and nothing under it

Context

Spec 5 states that a document can declare that it governs code, and that an edit to that code raises an advisory prompt. The glossary repeats it. Spec 2 makes anchor resolution a correctness root for the same reason.

Surface::governing_docs_for_path answers the query, and it compares the path it is asked about against the string each edge reached. The comparison is equality. Its own doc comment states the rule: the path is matched against what an edge reached rather than against a pattern. A resolver normalizes two spellings of one target into one node, and that is the whole of what the comparison tolerates.

The write-time hook of #72 measured the consequence. This repository first declared one governs edge from spec 5 onto .claude/hooks, which is the directory that holds the three hooks. The harness then reported an edit to .claude/hooks/write.sh. The engine reached no governing document and the hook wrote nothing. That answer reads exactly like the answer over a path that nothing governs at all.

An anchor also carries no pattern syntax. normalize is lexical and source-tree resolves the result against the tree. So .claude/hooks/** is a path that no file answers to, and the edge reports as unresolved.

This repository now declares four edges, one for each file under that directory, and the hook fires. Four edges for one fact is the measurement rather than the fix.

Obligation

The corpus owes a ruling on what a code_path anchor denotes. One file, or a subtree, and spec 2 states neither.

Under equality, an author pays one edge for every file that a document governs. Spec 3 names that cost as the thing that killed every prior design-rationale tool. A directory of forty files takes forty hand-typed edges, and HW-OBL-0105 records that nothing mechanical writes even one of them.

The failure mode is silence rather than error. A hook that finds no governing document exits 0 and reports nothing. A rename inside a governed directory produces an unresolved anchor, which a check does report, but a new file in that directory produces nothing anywhere. Impact detection is then green over code that a document governs in every sense except the one the engine reads.

The same silence covers a set that names no directory at all. HW-DR-0024 rules over three files, and the agent that drafted it named one. Nothing reported the two it left out. The anchor resolved, every check passed, and a document that governs one of three reads exactly like a document that governs one. So the gap is wider than the directory case above. A governs set has no denominator, and the author is the only reader who knows the full set.

The first-run walkthrough calls impact detection the most valuable thing the corpus does for a coding agent. Spec 5 makes the same claim in the same words. A mechanism that reaches one file for each declared edge is a smaller claim, and no document states which one holds.

Discharge

This record is discharged, and the ruling admitted a subtree. HW-DR-0074 rules that a code_path anchor's raw value is a pattern in the language of headwater_meta::pattern, or a list of such patterns. governing_docs_for_path matches the asked path against every pattern of every anchor, and never against the string an edge reached. A pattern with no wildcard resolves exactly as a bare path always has. So this closes with no edge in the corpus forced to change.

The containment test and the failing fixtures this record asked for. engine/crates/graph/src/anchors.rs holds a fixture over the pattern .claude/hooks/**. Its tree carries both .claude/hooks/write.sh and .claude/hooks-disabled/write.sh. The pattern reaches the first and never the second. That is the naive-prefix-test failure this record named. engine/crates/query/tests/reads.rs holds the query-layer proof over a real corpus. One document's pattern anchor now reaches a file under it that an equality match never could. A second document's list anchor reaches both members it names.

Four edges for one fact is not what the corpus pays now. An author who governs a directory of forty files writes one pattern instead. An author with several files already governed by hand may join them into one list anchor, at their own pace. Nothing in this ruling rewrites an edge nobody chose to change.