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

headwater route

Synopsis

headwater route <task description> [--budget <n>] [--json] [--root <path>]

Every word after route forms the task description. The verb takes no separate path operand.

Description

headwater route matches a task description to declared purposes, then ranks document pointers under those purposes. It reads summaries, facet values, paths and governance anchors. It does not search document bodies.

A task that names a governed source path receives the documents that govern that path before lexical ranking. Other tasks first match terms against declared purposes, then require a separating term to reach a document. This confidence gate prevents a common term from producing a guessed pointer.

Route does not follow a call or an import. A document that governs only a file which calls or imports the named path gets no pointer through that call. To reach that document from the named path, its author declares governs over the called file too. Route reads summaries, facets, relations and code-path anchors, which is the read set of spec 5, so it holds no call graph.

The default budget is five ranked pointers. Anchored pointers are never removed by the budget. The report states how many ranked pointers the budget withheld.

The matched purposes take turns at the budget, highest score first, and each offers its best remaining document at its turn. Inside one purpose, the kinds that serve it take turns the same way. So a task that matches several purposes receives pointers from several kinds. HW-DR-0070 rules this.

Each pointer states what reached it. An anchored pointer names the paths of the task that it governs. A ranked pointer names the distinctive task terms that reached it. It also gives its rank in the order by score before the turns. The text report prints this on a dim line under the pointer. No pointer carries a score or a confidence.

A pointer to a document that nobody accepted says so, in one of two wordings. The text report ends such a pointer with a bracket after the summary. For a document whose warrant is asserted, the bracket is [asserted: nobody accepted this document]. For a document whose declared warrant is outside the four values of spec 3, the bracket is [warrant `<value>` is not one of the four values: no acceptance is read from it], with the value as written. In JSON, both pointers carry unwarranted: true, and no member states the value. A document that declares no warrant, or a warrant key with no value, gets no bracket and unwarranted: false.

Text prints the task, matched purposes, pointers with their evidence and any silence reason. JSON carries those values, a stable silence token where appropriate and the text report from the same run. Silence is a result, not a failure.

A task can name a path that the governed scope admits and that no document governs. A word of the task is read as the path it names as written, where the tree holds that path. A file named src/a:b.rs or src/notes. is never read as a shorter path. Where the word as written names nothing, the verb reads it without the prose around it. That prose is a trailing period, brackets, a comma, a possessive 's and a :<line> suffix. It first takes the first reading that the tree holds. Only when the tree holds no reading does it take the first reading that an edge reaches. So a ** edge that admits write.sh's as a string does not win over the file write.sh on the tree. If no reading qualifies and something had to come off, the word names no path. A URL names no path. The MCP route tool holds no tree, so it reads a word through the edges alone. It keeps the longer reading that a glob edge admits. A word names such a path when five conditions hold. The word holds a /, and a scope pattern admits the path. The path is not a directory on the tree, git does not ignore it, and no governing edge reaches it. For each such path, the report states that the path is in the governed scope and that nothing governs it. It also prints the front-matter lines that declare the edge. It prints them once for each relation that governs and whose target admits the anchor kind of the scope pattern. The route writes nothing. A path outside the scope gets no such line. In JSON, the ungoverned array carries one object for each such path, with its path and its relations. The member is present on every run, and it is empty when no word names such a path. The pointers and the silence token do not change.

An anchored pointer can govern a named path through an edge that records a verified_revision. When the revision that the edge reaches now differs from the recorded one, the edge is suspect. The text report then prints one dim line under the pointer for each suspect edge. The line names the edge target and both revisions, and it says that headwater check reports the edge. An edge with no recorded revision is never suspect here. An edge whose target has no revision, such as a literal directory, is never suspect here. headwater check makes the same comparison, from the same function.

In JSON, each pointer carries an evidence object. Its by member is anchor or terms. With anchor, anchors lists the named paths that the document governs. suspect lists the suspect edges from that document to those paths, as objects with target, verified and current. The array is present on every anchored pointer, and it is empty when no edge is suspect. With terms, terms lists the terms that reached the document. rank is its place in the order by score, counted from 1, and of is the length of that order.

Preconditions

The repository must carry a readable .headwater/taxonomy.lock, consumer declaration and corpus. The corpus is loaded through the resolved taxonomy.

The task must contain at least one word of two characters or more after parsing. An empty task is refused before the corpus is loaded.

Options

Option	What it does
--budget <n>	Set the maximum number of ranked pointers. The default is 5.
--json	Write the route as a machine-readable JSON document.
--root <path>	Select the repository to read.
--no-color	Force plain text on both streams: bold and dim weight plus glyphs, no escape sequence. The default already senses whether each stream is a terminal, and renders color only there.
--no-banner	Suppress the masthead: the line naming this binary and its version, that the root help screen alone prints. It is accepted here and does nothing, since only the root screen prints one.

--format is not an option of this verb. --wide is refused because the verb prints no help layout. Global --help, --version and --no-banner are answered before the verb runs.

Exit status

0 means that the task was evaluated, whether pointers were offered or the route was silent.

1 means that the task was missing, an option was invalid, or the repository could not load. A silent route writes its normal report and still exits 0.

All three reasons for exit 1 are refusals, so standard output is empty on every one of them. Each is decided before anything is written, and the account is one English sentence on standard error. That holds under --json as under the report a person reads, which is what HW-DR-0043 rules.

1, and never 101, when standard output or standard error cannot be written, and one sentence on standard error names a failed standard output.

Environment

No environment variable reaches this verb. The task, budget and repository come from the command line, and the graph and corpus come from the tree.

Files

Path	How this verb treats it
.headwater/taxonomy.lock	Read for the taxonomy and graph declarations.
.headwater/taxonomy.yml	Read through the consumer loader.
The corpus	Read for typed documents, summaries, facets, paths and edges.
.headwater/imports/	Read where .headwater/taxonomy.yml declares an import, for the anchors that an imported snapshot supplies. An imports entry that does not read stops the verb with exit 1, and so does an at path outside the repository root.
the path each harvests.<name>.at names	Read where .headwater/taxonomy.yml declares a pinned corpus export, for the anchors that export supplies. A harvests entry that does not read stops the verb with exit 1, and so does an at path outside the repository root. A pin with no digest binds no anchor. An absent file binds no anchor, and neither does a file that fails the pinned digest or is not an export.

The verb writes no file.

See also

headwater explain reads the derivation and requirements of one pointer.

Spec 5 defines purpose matching, confidence gating, anchors and the pointer budget.

headwater mcp serves the same route read through a JSON-RPC tool.