llm-ingestion-okf/docs/plan/references-cue-rule.md

What a derived references subject is

Record of the decision taken 2026-08-29 on order …507632913, and of the measurement it rests on. Supersedes the reference half of docs/plan/structure-derivation.md; nothing else in that document moves.

The defect

STRUCTURED_V1 derived references by taking every number-shaped token in a document body. A consumer measured it on their own corpus and reported 12 false references out of 12, ten of them version numbers carried in titles and read as document numbers.

The order was not to inherit that figure. It was measured again here, on two corpora this repository can reach, before anything was changed.

Measured before the change

Both figures come from derive_document_structure itself, run over every unique document (deduplicated by sha256) and counting the subjects it returns with references marked derived.

corpus	documents	documents with derived references	subjects
A — a consumer's normative bundle set, six bundles, Norwegian	2 561	1 010	2 838
B — this repository's own docs/, English and Norwegian technical prose	28	27	559

What those subjects were, classified against the position the scanner actually lifted each one from:

• Corpus A. 702 of 2 838 (24.7 %) were hexadecimal fragments of UUIDs read out of id="…" attribute values inside embedded HTML and MathML. The rest of the false population was unit symbols (kN/m2 reduced to M2), table row and class labels, and formula numbers.
• Corpus B. Dominated by software versions (v0.3.0, 3.14.0, 0.11.10, 1.28.2), a licence identifier (AGPL-3.0 → 3.0), a container format version (%PDF-1.6 → 1.6), a hash algorithm name (SHA256), and tokens lifted out of two-character escape sequences inside quoted source (\n60 → N60).

The consumer's reported class reproduces. Two classes they did not report — identifier fragments inside markup, and escape-sequence artefacts — are larger.

The decision

A derived reference subject is one of exactly two things: a bundle-local markdown link target, or a number immediately preceded by a reference cue from a closed set. Everything else number-shaped in body prose is not a reference.

The rule is positive rather than a blacklist, and that is forced by the data, not chosen for taste: corpus A proves V221 and V240 are genuine document numbers, corpus B proves V0.3.0 is a software version, and the two are the same token shape. Nothing structural separates them. Only the words in front of them do, so only a positive cue can be defended.

The cue must match at a word boundary. Without that guard a Norwegian compound ending in -klasse satisfies the cue se, which admitted 86 class designations on corpus A. The window is normalised to NFC first, so a cue carrying a Norwegian letter matches whether the file arrived composed or decomposed.

Two link targets are also excluded, on the same ground rather than a new one: a fragment-only target (#anchor) points inside the document it appears in, and a target carrying a brace is a template placeholder from prose about links. Neither can name a concept — reduce_to_id_grammar emits lowercase alphanumerics and hyphens — so neither is a pointer awaiting resolution. It is a claim that cannot come true.

Measured after the change

Same script, same corpora, HEAD against the working tree.

corpus	subjects before	subjects after	dropped
A	2 838	1 279	1 559 (54.9 %)
B	559	72	487 (87.1 %)

Precision was checked by hand against the occurrence that actually passed the gate, not the subject's first occurrence in the file — reading the first one mis-attributes context and was a real error in an earlier pass of this measurement.

• Corpus A: 30 subjects drawn at random from 1 279. 30 of 30 genuine.
• Corpus B: all 60 cue-gated subjects. 60 of 60 genuine.

Residual known false positives: 9 of corpus B's 72, all in the link channel, all illustrative targets in prose about link syntax (link, target, /sti, subdir/). They are indistinguishable from real relative paths without guessing at path semantics, so they stay. Corpus A's link channel is empty, so this residue is not visible there at all.

The cost, stated rather than hidden

A corpus whose cross-references are phrased outside this vocabulary — a third language, a house style — derives nothing, and must declare references itself. That is the intended failure: a missing reference is visible to the reader, a false one is not.

Two recall losses inside the corpora measured, both accepted: a reference whose cue is a preposition (i henhold til … where the noun is absent) and one written as a prefixed compound (N-V240) are dropped.

What was deliberately not done

The prefix-resolution rule (N130 in a body not finding a document numbered N130.2) stays open. The order allowed it in the same pass only if the data bore it. It does not: of 2 589 documents across both corpora, 2 562 carry a number and 0 of those numbers are dotted, so a unique-prefix match has nothing here to be defended against. Closing two things badly is worse than closing one well.

Adjacent defect found, not fixed — needs its own order

The line-oriented frontmatter parser lets a nested key overwrite a top-level key of the same name. A sources: block whose entry carries its own title: replaces the document's title, and the number derived from that title follows it. This is the same family as the known block-list finding but strictly worse: that one drops a value silently, this one substitutes one. It changes title, number and parent, so it is outside this order's scope, and it is why corpus A's numbers above are what they are.