okf-wiki/docs/x-fields.md
Kjell Tore Guttormsen 0fd86a23a3
okf-wiki 1.1.1
First public release, published as one snapshot. What changed between
versions is in CHANGELOG.md.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
2026-11-14 21:03:20 +01:00

7.6 KiB

x- fields

okf-wiki writes a few frontmatter keys of its own. SPEC § 4.1 allows them ("Producers MAY include any additional keys"), and format choice (g) in PLAN.md § Rammer puts quote and locator in x- keys because no upstream proposal offered a standard field. Criterion 5 asks that every x- field has a measured reason in the repository, so the reason stands here, in the table, with its measurement and its number: why the standard does not hold, and where a field could move if Google adopts one.

How the rows were found (wave 2 order 7, 09.10.2026): grep -oE '\bx-[a-z][a-z0-9-]*' over okfwiki/ and skills/ (the fields the code and the skill write or read; tests/test_x_fields.py keeps this table equal to that list), and the x- keys on the pages of the built collections on the bench (P1's K, 212 pages; the L2b and L4 slices, 151 pages each). SPEC is read at the pinned commit ad30107, where grep -oi counts the words named below.

tools/x_fields_check.py BUNDLE fails when a page carries an x- field with no row, at another place than its row says, or with the status "not in v1", and when a row has no reason or a reason with no number in it besides references (section, issue and point numbers, names such as K2, dates, commit ids).

Field Where Status Written by Read by Meaning Measured reason Standard field if Google adopts one
x-quote sources[] v1 okfwiki/kassemble.py okfwiki/audit.py, okfwiki/claims.py, okfwiki/view.py; the skill The words, copied character for character, from the source line the claim rests on. SPEC § 5.1 names 7 keys for a sources entry (resource, id, title, author, usage_count, last_modified, usage_window) and the word "quote" stands 0 times in SPEC.md, so the standard cannot hold the verbatim support criterion 1 asks for. On P1's K 895 of 895 entries carry one, and the auditor finds each at its locator (mutant gate: m03 quote-not-verbatim caught). A quote or excerpt key on a sources entry; none proposed upstream (survey of 26.09, issues #8-#32).
x-locator sources[] v1 okfwiki/kassemble.py okfwiki/audit.py, okfwiki/claims.py, okfwiki/view.py; the skill Where the quote stands in the raw source: { line: N }, and for a PDF or Office source also its place in the original, page, paragraph, sheet and cell, or slide and notes (the locators of the file-type gate), which the auditor checks against the frozen copy's places. A spreadsheet row is one line, so cell is the cell the quote covers, or a range (B5:C5) when it covers more; the auditor checks that it lies in that row. "locator" and "line number" stand 0 times in SPEC.md, and § 6.2 says nothing of fragments, so the line cannot go into resource. Criterion 1 checks the quote on that line: 895 of 895 entries on P1's K carry one, 664 of 664 claims cited (mutant gate: m04 quote-wrong-locator caught). A locator key on a sources entry; none proposed upstream.
x-span sources[] v1 okfwiki/kassemble.py none in okfwiki/ (the trial's measure reads it) First and last line of the source block the fragment was written from: [start, end]. "span" stands 0 times in SPEC.md, and x-locator names one line. A claim can draw on more lines than the one it quotes: P1's precision count, read from this field, put 59 of 650 fragment entries on a span of more than one line and 591 on one line. A locator range on a sources entry; none proposed upstream.
x-provenance sources[] v1 okfwiki/kassemble.py okfwiki/audit.py (counted per value); wave 2 order 9 selects the claims to read by it (K6) How the claim follows from its quote: documented, inferred or merged. In SPEC "provenance" (12 times) is the list of sources only, and § 5.1 puts deeper lineage "out of scope for v0.2": 0 of the 7 entry keys says how a claim follows from its source. 59 of 650 fragments on P1's K rest on more than their quoted line; criterion 2 reads every claim marked inferred or merged on the rest of collection 1, plus a sample of at least 300. A per-claim derivation key, if a later version brings lineage into scope.
x-merge-candidate page v1 okfwiki/kassemble.py none in okfwiki/ (the trial's measure reads it) The id of an existing concept whose name is close enough (word Jaccard of 0.6 or more, kpack.MERGE_JACCARD) that this page may duplicate it. "merge", "duplicate" and "alias" stand 0 times in SPEC.md, so a page cannot say that it may be another page. P1's K built 3 duplicate pages among 212 (title Jaccard), with 0 flagged. A same-as or alias relation between concepts; none proposed upstream (#16, #22 and #30 move toward stable ids).
x-main-for page v1 okfwiki/kassemble.py, from the model's choice of main page (wave 2 order 10) okfwiki/audit.py (contract K2) The sources, as / + their K1 path, this page is the main page for. "main page" stands 0 times in SPEC.md, and § 4.1 resource is one URI for the asset a concept describes, not the documents it is the main page for (K2 point 8). The frozen copy's K1 lists 195 documentation sources with main_topic: true, each needing exactly one main page; the mutant gate holds 11 cases for the rule, matched 11 of 11. A key naming the documents a concept is the main page for; none proposed upstream (K2 point 8).
x-aliases page v1 okfwiki/kassemble.py, from the build's catalogue (WORK/K-work/index.json), where okfwiki/kmerge.py puts the name of each page merged in okfwiki/serve.py (through the index line, where the names end the entry as (also: A; B)), okfwiki/view.py The concept's other names, in the catalogue's order: each alias that is not the title, once, with case set aside. "alias" stands 0 times in SPEC.md, and § 4.1 tags are "short strings for cross-cutting categorization", not names of the concept. After the merge of collection 1 (12.11.2026) 48 of 118 merged pages carried a longer name than one that went into them, and the 171 names of the pages merged in stood on no page, in no index line and in no search: only in the build's catalogue. An alias or same-as key on a concept; none proposed upstream (#16, #22 and #30 move toward stable ids).
x-outdated page not in v1 none in v1 (the skill marks an outdated claim in the text, not in a field) okfwiki/view.py (versions: a sentence citing an outdated pair is dated history) Pairs of footnote labels { old, new }: the old claim is outdated by the new. "outdated" stands 0 times in SPEC.md, and "supersede" 3 times, each about SPEC's own versions (§ 13). On the L4 slice 6 pairs on 4 of 151 pages kept 12 sentences of dated history out of the count of version numbers in running text (PLAN.md § Logg, 28.09; rewriting sentences, not the pairs, brought that count to 0). Outdated-marking is not in v1 (CLAUDE.md), so a v1 page with it fails the check. supersedes (#22, open), format choice (h).

Seen only on the pages of P1's trial, never written by v1 code (grep over okfwiki/ and skills/: 0 hits each), so a v1 page with one fails the check: x-fragments (on 212 of 212 pages of P1's K) and x-quote-by (on 160 of its 895 source entries). They are written by the trial code in evals/p1/, as was the trial's own x-aliases (on 212 of 212 pages), which is not the field in the table.

x-disputed (pairs of labels whose sources contradict each other) stood in the skill until wave 2 order 10, which marks a dispute in the text and its quotes instead, with no frontmatter field (skills/okf-wiki/SKILL.md, "When sources disagree"). It had 0 uses: 0 of 151 pages in the L2b and L4 slices and 0 of 212 on P1's K. With no row, a page that carries it fails the check.