Rendered from docs/obligations/0181-an-unresolved-prose-link-reaches-a-run-as-a-graph-fact-and-no-rule-turns-it-into-a-finding.md in the Headwater corpus. Every document on this half of the site is typed by the taxonomy the descriptor names: corpus.json.

An unresolved prose link reaches a run as a graph fact and no rule turns it into a finding

Context

headwater check counts the links it could not resolve. It prints the count in the graph section of its report, with the file, the line and the reason. The count is a statistic about the run. No rule reads it, so no finding carries it, --strict does not fail on it, and headwater infer cannot record it as pending debt.

The near rule is link.fragment.unresolved, and it is a different rule. It reads a fragment inside a document, which is the part after the hash. A link whose path does not exist at all is outside what it asks.

The n8n evaluation measured one instance in somebody else's corpus. packages/@n8n/expression-runtime/ARCHITECTURE.md:426 points one directory too high, the run printed 1 prose links that did not resolve, and the same run reported 12 findings, none of which was this one. A person reading the graph section found it. Nothing in the report would have raised it.

That instance is now also a finding, and this obligation is not answered by it. The same fixture re-run at headwater/standard 4.3.0 reports 13 findings, and the thirteenth is link.path.unresolved on that link. So one rule does read an unresolved path in that fixture's bundle. The graph statistic is unchanged. headwater check still prints 1 prose links that did not resolve as a count that no rule reads. --strict still does not fail on the count, and headwater infer still cannot record it. A rule that happens to cover the same link in one bundle is not the decision this record asks for.

Three obligations already in the register look like this one and are not. HW-OBL-0116 and HW-OBL-0117 are about anchors in imported documents. HW-OBL-0136 is about rustdoc links inside comments. None of the three asks what happens to a link in prose whose target path is absent.

Obligation

The corpus owes a decision on whether an unresolved path in a link is a finding, and at what severity. The remedy is mechanical only when the intended target can be derived. It is a rewrite when it cannot, so spec 12's fixability bar points at advisory rather than error. Until the decision is taken, this corpus and every corpus that adopts this taxonomy carries broken references that a green strict run says nothing about.

Discharge

A rule that turns an unresolved link target into a finding discharges this. It is declared in the taxonomy and implemented with a fixture that fails before it passes. A ruling that the graph-section count is the right place for the fact, written where a reader of the report meets it, discharges it too. Either one closes it. Leaving the count in the graph section with no ruling does not.

This record is discharged. The rule link.path.unresolved is in engine/crates/check/src/link_path.rs, and the base package binds it to OB-LINK-2 at the advisory posture. The owner ruled on 2026-09-30, in the roadmap review of that day, that advisory is the correct posture.