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>
This commit is contained in:
commit
0fd86a23a3
227 changed files with 96077 additions and 0 deletions
41
docs/known-limitations.md
Normal file
41
docs/known-limitations.md
Normal file
|
|
@ -0,0 +1,41 @@
|
|||
# Known limitations of v1
|
||||
|
||||
The review of v1 (06.11.2026) found 2 BLOCKER and 48 MAJOR findings. Both BLOCKERs and the MAJOR findings that are
|
||||
defects were fixed, each with a test. The MAJOR findings below were accepted: each one is a gap or a limitation, not
|
||||
wrong behaviour on the build path, and the reason is given. The finding numbers are the review's own order.
|
||||
|
||||
## Guards that work but have no test of their own
|
||||
|
||||
The guard exists and was read in the code; what is missing is a test that would catch a regression in it.
|
||||
|
||||
| # | Where | Untested guard |
|
||||
|---|---|---|
|
||||
| 12 | `gates/answers.py` | breach rules for find actions, `sed -i`, absolute Glob patterns, unparseable Bash |
|
||||
| 14 | `gates/answerset.py` | gate on the held-out set; the threshold refusal; freeze without `subset_of` |
|
||||
| 15 | `gates/calibration.py` | the layout's refusal when too few distinct fillers remain; duplicate call names |
|
||||
| 18 | `gates/repair_gate.py` | the fix-case judgement (diff, excerpts, findings) on a handmade result |
|
||||
| 27 | `okfwiki/kassemble.py` | refusal of reserved (`index`, `log`) or unsafe concept ids |
|
||||
| 28 | `okfwiki/kassemble.py` | the stop after an unfinished swap (`.<out>-old` left behind) |
|
||||
| 31 | `okfwiki/kmerge.py` | the marked write: backup, marker and the recovery stop |
|
||||
| 34 | `okfwiki/kpack.py` | refusals to overwrite parts, home tasks, logs and the floor file |
|
||||
| 36 | `okfwiki/krepair.py` | `unknown-key` and `ambiguous-key` refusals in `task` and `fix` |
|
||||
| 37 | `okfwiki/krepair.py` | `relink --work` and its logged `moved` record |
|
||||
| 40 | `okfwiki/sources.py` | freeze's refusal of a bad name, a folder and a symlink; some `check` refusals |
|
||||
|
||||
## Measurement tooling
|
||||
|
||||
| # | Where | Limitation | Why accepted |
|
||||
|---|---|---|---|
|
||||
| 13 | `gates/answerset.py`, `gates/multidoc.py` | run from a git worktree nested in the main checkout, a held-out path in the main checkout is not refused | run the answer-set tools from the main checkout |
|
||||
| 16 | `gates/calibration.py`, `okfwiki/reader.py` | the gate reads the verdicts file twice (the green-run record now has one shared parser) | extra reading, not a wrong result |
|
||||
| 22 | `okfwiki/cost.py` | user text between an unrecorded message and the next is counted as derived output | it can only raise measured cost, so the cost stop comes earlier, never later |
|
||||
| 23 | `okfwiki/cost.py` | derived output before the first helper is projected per batch | it can only raise the projection, which is reported, not used to stop |
|
||||
| 25 | `okfwiki/cost.py` | `cost isolation` takes no list of breaches set aside | the rule that asked for it was removed with the rule cut of 06.11.2026 |
|
||||
| 26 | `okfwiki/cost.py` | the read and diagnose breach count looks only at Read calls | the reader and diagnoser agents are given the Read tool only |
|
||||
|
||||
## Other
|
||||
|
||||
| # | Where | Limitation | Why accepted |
|
||||
|---|---|---|---|
|
||||
| 3 | git history | three merge commits (62d5438, 73e5bf7, ad63d41) are not Conventional Commits | published history is not rewritten; later merges use `merge(...)` |
|
||||
| 39 | `okfwiki/reader.py` | when `collect --gate-passed` refuses a model, an older verdicts file at `--out` is left in place | `collect` exits 1, and the skill then runs the calibration gate on that model before anything is scored; deleting the earlier file would destroy a valid reading |
|
||||
72
docs/rule-decisions.md
Normal file
72
docs/rule-decisions.md
Normal file
|
|
@ -0,0 +1,72 @@
|
|||
# Rule decisions: the standing rules of `llm-ingestion-okf`
|
||||
|
||||
This file decides every standing rule from the old repository's `CLAUDE.md`, one row per rule, as operator decision U8 requires. The old `CLAUDE.md` is **not** carried over. A standing rule in `okf-wiki` exists only if it is listed here as kept or changed; everything else is gone.
|
||||
Rows follow the inventory of 25.09.2026, § 2 (2.1, 2.2, 2.3): 58 numbered rows (R1–R63 with R15, R24 and R34 absent, R17/R18 and R51–R52 grouped as one row each) plus 4 unnumbered rows. Open inventory rows are settled by the approved plan (`PLAN.md`: § Rammer with format choices (a)–(h), § Ikke i v1, § Leveranser, and the coverage table) and by operator decisions U5–U8.
|
||||
"Keep" means the substance stays (the wording may be adapted to the new product). "Change" means the substance changes. "Drop" means the rule does not exist here.
|
||||
|
||||
| Old rule | Rule (short, paraphrased) | Decision (keep / change / drop) | New wording (if keep or change) | Reason (one sentence) |
|
||||
|---|---|---|---|---|
|
||||
| R41 | No model call anywhere in the run path. | change | Shipped tools (auditor, MCP server) never call a language model or Claude Code. Model work happens in the user's own Claude Code session through the skill. | Binding operator rule U8 (1): the ban still holds for the tools, but the old wording no longer describes a product where the session writes the wiki. |
|
||||
| — (okf never starts Claude Code) | The tool never starts Claude Code. | keep | No shipped tool starts Claude Code or any model process. | Same rule as U8 (1), kept as its own line because it is the one users can check most easily. |
|
||||
| R39 | Output is bit-exact: explicit timestamps, LF only, golden files compared byte for byte. | change | Bit-exactness applies to the auditor's own outputs (raw-source layer, generated index, reports, HTML view), not to wiki pages. | Wiki pages are written by a model in the user's session and cannot be bit-exact (plan § Rammer). |
|
||||
| R36 | Exactly one runtime dependency, ever (the guard), enforced by a test. | change | Every runtime dependency is named and justified in the repo. PyYAML is one; the guard is not. | The auditor must read real YAML the way Google's reference does (plan format choice (c)), and screening is an optional report, not a gate (plan coverage table, inventory question 3). |
|
||||
| R30 | Structured frontmatter is written in YAML flow form, never block form. | drop | — | The session writes frontmatter now, and the auditor reads both forms with a real YAML parser (plan format choice (c)). |
|
||||
| R31 | Every value must read back the same through a YAML reader; `src/` imports no YAML library. | change | Every frontmatter block must parse as YAML (SPEC § 11). The auditor parses with PyYAML with timestamp resolution off, as Google's reference does. | Parseable YAML stays as a check, while the ban on a YAML import is dropped by plan format choice (c) and inventory question 5. |
|
||||
| R27 | Format support is additive through profiles; the default profile is OKF v0.1; version value owned elsewhere. | drop | — | The new repo has one profile, OKF v0.2, with the version written quoted on the root `index.md` (U4). |
|
||||
| R33 | The repo is a black box for its consumers; releases must not change consumer outputs. | drop | — | There are no consumers yet; the rule returns when something depends on `okf-wiki`. |
|
||||
| R35 | Non-goals: embedding, retrieval layers, verdict machinery, security. | change | Non-goals: shipped tools never write wiki content and never call a model; vector search and knowledge graphs are out of v1; a search index of our own is built only if L4 measures a need. | The old repo built a retrieval layer despite this non-goal, and the plan sets the new limits (plan § Ikke i v1, coverage table item 4, U5). |
|
||||
| R19 | v1.0.0 is the scope the tool is finished at; later work only fixes defects. | drop | — | The restart replaces it, and "done" is now defined by `PLAN.md` § Ferdig-kriteriet. |
|
||||
| R25 | Standing posture: only defects, improvements and requested features. | drop | — | `PLAN.md` steers the work. |
|
||||
| R1 | Implements an ingest spec owned by another repository; spec changes go through that repo. | drop | — | The format is Google OKF v0.2 as published (U4); no external ingest spec applies. |
|
||||
| R22 | Implementation baseline taken from an earlier project, which is also the first consumer. | drop | — | That baseline and consumer belong to the old purpose (U6: nothing from the old purpose). |
|
||||
| R23 | Five-phase roadmap, including a second-language port for other repos; halves share contract, not code. | drop | — | `PLAN.md` § Leveranser replaces the roadmap. |
|
||||
| — (never enumerate a directory) | Nothing enumerates a directory unless the profile says the index is derived. | drop | — | A generated index built from frontmatter must walk the wiki directory. |
|
||||
| R28 | Rollout is pilot-first; flipping a version alias is the general-availability event. | drop | — | There are no users to roll out to; the rule can return when there are. |
|
||||
| R29 | No profile hard-codes an upstream version; attestation runtime deferred until upstream specifies it. | change | The OKF version is set in one place and follows upstream (R26). Attestation and attested computation are not built in v1. | We own the choice of v0.2 (U4), and attested computation belongs to the old purpose (U6, plan § Ikke i v1). |
|
||||
| — (§ 14 references) | Code and docs cite a SPEC § 14 that forbids consumers to reject. | drop | — | That section does not exist in the spec and the code citing it is not ported; conformance references in the new repo cite SPEC § 11. |
|
||||
| R26 | The tool always supports the latest version of Google OKF. | keep | The repo supports the latest published Google OKF, and upstream is checked at least weekly. | Operator decision U4 and the standard rule in plan § Rammer. |
|
||||
| R32 | Every upstream release runs the upgrade runbook: pin, read the whole tree and example bundles, classify, measure exposure. | keep | Every upstream release is handled with the upgrade runbook, `docs/upstream-runbook.md`. | It is the mechanism that makes R26 hold (U4). |
|
||||
| R3 | All file-type-to-text extraction lives in this repo. | keep | All file-type-to-text extraction lives in the auditor. | The auditor alone produces the locked raw-source layer that quotes are checked against. |
|
||||
| R9 | PDF and Office readers come only through an optional extra; without it such files are refused at once. | keep | PDF and Office readers are an optional install extra; without it those files are refused with a clear error. | The base install stays small and a missing reader fails loudly instead of silently (plan § Rammer, reading rules). |
|
||||
| R37 | The PDF text library is pinned to one exact version; widening it is a fixture migration. | keep | The PDF text library is pinned exactly; changing the pin is a fixture migration. | The quote check needs the same raw text on every run. |
|
||||
| R4 | HTML is kept out of the document converter because of CVE-2025-51591; fixes go in the extractor. | keep | HTML is read by our own extractor, never by the document converter; fixes go in the extractor. | The known vulnerability still applies, and HTML is a v1 file type (U6). |
|
||||
| R5 | Text is preserved exactly, not measured as a percentage. | keep | The raw-source layer preserves source text exactly; preservation is checked as exact, never as a percentage. | Verbatim quote checks at a locator only work on exact text. |
|
||||
| R6 | Input with a DOCTYPE declaration is refused unparsed, with its own error code. | keep | Input with a DOCTYPE declaration is refused before parsing, with its own error code. | The auditor reads untrusted files, and refusing before parsing keeps that input away from the parser (plan § Rammer, reading rules). |
|
||||
| R11 | Structured table recovery is out of scope; PDF enters as prose; figures do not survive. | keep | Known limitation in v1: no structured tables, PDF enters as prose, figures are not carried. | Tables, images and figures are a separate later delivery (U6, plan § Ikke i v1). |
|
||||
| R2 | Recursive walk; source path is relative; collisions refused; dot-directories and nested bundles skipped with a code. | keep | The raw-source layer is built by a recursive walk with relative source paths; collisions are refused; dot-directories and nested wikis are skipped with a code. | Stable, unique source paths are what locators and `sources[].resource` point to. |
|
||||
| R40 | File names and titles are NFC-normalised. | keep | File names and titles are NFC-normalised. | Filesystems that return decomposed Unicode would otherwise break paths and quote matching. |
|
||||
| R43 | Network access needs an explicit opt-in per run. | keep | Network access needs an explicit opt-in per run. | The auditor works offline by default, and only named jobs such as the weekly upstream check may use the network. |
|
||||
| — (remote images) | Remote images are never fetched; no live remote link. | keep | Remote resources referenced in source documents are never fetched, and pages we generate carry no live remote image link. | Reading sources must not reach the network; Google's graph view, shipped unchanged as an add-on, loads its own libraries and is the one noted exception. |
|
||||
| R21 | Never reimplement security screening; when unsure which side of the boundary something belongs, ask the operator. | keep | Security screening of documents is not reimplemented here; the external guard, when used, runs as an optional report. When unsure where something belongs, ask the operator. | The principle holds even with the guard optional (plan coverage table, inventory question 3). |
|
||||
| R17/R18 | The gate name is logged; refusals are loud (count, names, way out); a loud message never moves the exit code. | keep | Every refusal states the count, the names and the way out. A warning never changes the exit code; only a failed check does. | Loud refusals are a method rule in plan § Rammer; the old guard-specific mechanism goes with the guard. |
|
||||
| R12 | Every derived field is named; an unmarked heuristic is worse than none. | keep | Everything generated is marked: `generated.by` for the writer, `verified` only for a human check; the auditor never writes `verified`. | SPEC § 5.2–5.3 carry the principle, and plan format choice (e) says a quote check proves presence, not truth. |
|
||||
| R13 | Locator keys sit at the top level because the pinned guard rejects extra keys in a `sources` entry. | change | Quote and locator are carried in `x-` prefixed fields; the guard is not a gate on wiki pages, so its key limit does not apply. | No standard field for them exists upstream (plan format choice (g)), and the guard is optional (inventory question 3). |
|
||||
| R14 | The index is a projection of the whole bundle; a full rebuild equals an incremental update byte for byte. | keep | The generated index is a projection of the whole wiki; a full rebuild and an incremental update give the same bytes. | It keeps the index honest and testable. |
|
||||
| R47 | Every path assertion runs its pattern against a known-positive case first. | keep | Every pattern or path assertion is first run against a known-positive case. | An empty result only means something when the query is shown to find a known case. |
|
||||
| R48 | Timestamps default to a shared epoch constant, never the clock. | keep | Timestamps in auditor outputs default to a shared epoch constant, never the clock. | It is what makes R39 hold for the auditor's outputs. |
|
||||
| R38 | Type checking with `mypy --strict`. | keep | `mypy --strict` passes on all shipped code. | Method rule listed in plan § Rammer. |
|
||||
| R44 | Conventional Commits; English in code and documentation. | keep | Conventional Commits; English in code and documentation. | Method rule listed in plan § Rammer. |
|
||||
| R54 | Public tests run on invented material; a gold set is an input, never a constant; a held-out part is kept; ways to game a gate are shared. | keep | Public tests and gates run on invented material; a gold set is an input, never a constant; a held-out part is never used during development; known ways to game a gate are written down and tested. | The plan holds back 20 questions and tests the auditor against mutants (plan § Styrke og regime, § Leveranser E); the retired corpus track itself is not carried. |
|
||||
| R55 | A check with no measured threshold is never PASS. | keep | A check with no measured threshold never reports PASS. | Method rule listed in plan § Rammer. |
|
||||
| R59 | TDD: no production code without a failing test first. | keep | No production code without a failing test first. | Method rule listed in plan § Rammer, and the evals are written red first (plan § Leveranser E). |
|
||||
| R60 | Public repo; STATE and the startup prompt stay local; no secrets; no marketing language. | keep | STATE and session prompts stay local, there are no secrets in the repo, and there is no marketing language. The repo starts private; making it public is the operator's decision. | Binding operator rule U8 (2); the private start comes from U9. |
|
||||
| R61 | Consumer content only at form level in public files; Anthropic-derived prose is not published. | keep | Prose derived from Anthropic documentation is never published: the Claude Code documentation test set and its question sets stay local, and only their form is published. | Binding operator rule U8 (3). |
|
||||
| R62 | Push to Forgejo after each commit; never GitHub. | keep | This repo is hosted on Forgejo only, pushed after each commit, never on GitHub. | Binding operator rule U8 (4); reading Google's upstream repository for the weekly check is not hosting. |
|
||||
| R63 | Links to local files are written as named `file:///` links. | keep | Links to local files are written as named `file:///` links. | The operator opens files by clicking, not by reading paths (plan § Rammer, method rules). |
|
||||
| R7 | A document with no structure yields zero plans and a failed build. | drop | — | Segmentation is gone. |
|
||||
| R8 | Extractor registries are coupled to the segmentation registry. | drop | — | Segmentation is gone. |
|
||||
| R10 | Converter attribute in titles; renaming concept ids is an operator question. | drop | — | Concept ids from segmentation are gone; page names come from the skill. |
|
||||
| R16 | Door C: verbatim merge, ownership through content identity. | drop | — | The merge path is gone; the skill chooses existing pages before writing new ones (plan § Leveranser L2). |
|
||||
| R20 | A fenced code block declares no structure (CommonMark details). | change | When the auditor parses wiki pages for headings, claims and links, text inside a fenced code block declares no heading and no link, following CommonMark. | Criterion 1 excludes headings from the claim count, so the auditor must find headings correctly (plan § Ferdig-kriteriet). |
|
||||
| R45 | The project command is byte-equal to the build command; only a gate flag moves bytes. | drop | — | Both commands belong to the old pipeline. |
|
||||
| R46 | The generated consumer skill has three modes (question, hypothesis per premise, document) with fixed markers and relative paths. | change | The skill's question part answers a question, a hypothesis per premise (confirmed, refuted, or not enough evidence in the wiki), or a document request, always citing page and source with relative paths. | The idea moves into the new skill's question part (plan § Leveranser L2, coverage table D6); the old code is not ported. |
|
||||
| R49 | Ten segmentation rules on by default, more behind flags. | drop | — | Segmentation is gone. |
|
||||
| R50 | PDF reader flags; OCR is an optional group, never a runtime dependency. | change | OCR is an optional install group, never a runtime dependency. A PDF page without a text layer is reported as an exception in the auditor's output. | OCR stays optional, and plan § Ferdig-kriteriet requires every exception to be stated with a reason; the old flags go with the old reader. |
|
||||
| R51–R52 | Image path limits, standard-library decoder, image library rejected; every carried image can be shown to a model. | drop | — | Images are not in v1 (U6, plan § Ikke i v1, coverage table item 4). |
|
||||
| R53 | Content accounting: the witness imports no package module; a mutation harness is a gate; opt-in. | change | Content accounting is not built in v1. The method stays: every check is tested against mutants, and a check's witness does not import the code it judges. | Accounting is out of v1 (coverage table item 4), while the mutant method is the core of the eval delivery (plan § Leveranser E). |
|
||||
| R56 | MCP server: standard-library JSON-RPC to avoid a second dependency; no caching between calls; path containment with two independent checks; the form is the operator's choice. | change | The MCP server is read-only: it serves lookups of pages, index and sources across several wikis, never writes, caches nothing between calls, and confines every path to the wiki root with two independent checks. New dependencies follow R36. | U5 decided the form (server, read-only, several wikis), which settles the open choice. |
|
||||
| R57 | The server is the standard way in and the skill is the supplement; a derived card is never written. | change | Server and files are both ways in: the MCP server serves lookups, plain file search always works beside it, and the skill writes. The server stays only if it measurably helps on cross-document or cross-wiki questions; otherwise it is simplified. | U5 answered the operator's choice with "both" (coverage table, inventory question 2) and set the measure (plan § Leveranser L4, L5); the card concept is gone. |
|
||||
| R58 | BM25 ranking is the default, with lookup flags. | drop | — | BM25 is used only if L4 shows a need (coverage table item 4). |
|
||||
| R42 | Credentials only as environment-variable references. | drop | — | There are no connectors in v1 (U6: database and network connectors are out), and "no secrets" is covered by R60. |
|
||||
|
||||
62 rules: 29 kept, 13 changed, 20 dropped
|
||||
117
docs/upstream-runbook.md
Normal file
117
docs/upstream-runbook.md
Normal file
|
|
@ -0,0 +1,117 @@
|
|||
# Upstream OKF upgrade runbook
|
||||
|
||||
Rule R26 (`docs/rule-decisions.md`): this repository supports the latest published Google Open Knowledge Format, and
|
||||
upstream is checked at least weekly. Rule R32: every upstream release is handled with this runbook. `CLAUDE.md`
|
||||
§ The standard: `SPEC.md` at the pinned commit is the source of truth.
|
||||
|
||||
A standing policy without a procedure is an intention. Each step below names the failure it prevents; each of those
|
||||
failures happened in an earlier round of the same work, not in theory.
|
||||
|
||||
## Trigger
|
||||
|
||||
The morning job (`tools/upstream_watch.py`, daily at 07:15) sends a coord message when canonical has moved past our
|
||||
pin in a path that bears the contract, and when issues or pull requests are new or changed. The message is the trigger
|
||||
to run this runbook, never its result: the job sees commits, numbers and times, not meaning.
|
||||
|
||||
Run the runbook also without a message when a session reads upstream for another reason and finds a change. Record the
|
||||
result in `PLAN.md § Logg` **even when nothing changed**: an unrecorded check cannot be told from a skipped one.
|
||||
|
||||
The canonical home is `GoogleCloudPlatform/open-knowledge-format`. Our pin is `PIN` in `tools/upstream_watch.py`.
|
||||
|
||||
## Step 1: pin before reading anything
|
||||
|
||||
Record the exact commit SHA you are about to read, and read everything at it.
|
||||
|
||||
*Prevents:* reading a moving branch and treating the result as fact. Two readers of `main` are one unstable reference
|
||||
read twice, and a spec edited after a migration commit makes "the migration commit" and "the current spec" two
|
||||
different objects.
|
||||
|
||||
## Step 2: enumerate the whole repository tree
|
||||
|
||||
List every file at the pinned commit before deciding what to read, starting at the root:
|
||||
|
||||
git ls-tree -r --name-only <sha> | awk -F/ '{print $1}' | sort -u # top-level entries
|
||||
git ls-tree -r --name-only <sha> | sed 's/.*\.//' | sort | uniq -c # kinds of file
|
||||
|
||||
*Prevents:* assuming the folder you know is the one that matters. A negative claim from a partial enumeration ("there
|
||||
is no validator upstream") reads exactly like a measured one, and was wrong when it was last made.
|
||||
|
||||
## Step 3: read the shipped example bundles, not only the normative text
|
||||
|
||||
A spec says what is permitted; an example shows what upstream emits. Read the bundles upstream ships under the pinned
|
||||
commit at byte level: check for a BOM, the final newline, and whether a value is quoted. A fetch that converts to
|
||||
markdown or summarises destroys exactly those three properties.
|
||||
|
||||
*Prevents:* freezing a page shape that conforms to the text but not to what upstream's own tools write. Earlier rounds
|
||||
learned from the examples, not the spec, that the root `index.md` carries no frontmatter, that `generated` is written
|
||||
for human-authored content too, and that real frontmatter is block YAML with nested mappings.
|
||||
|
||||
## Step 3a: run upstream's own reader against our pages
|
||||
|
||||
The reference reader (`src/reference_agent/bundle/document.py` at the last pin) imports only `yaml`. Run it from the
|
||||
pinned clone, without installing anything, over a built collection and over the mutant gate's known-positive bundle
|
||||
(`gates-local/mutants/`), and record per page:
|
||||
|
||||
1. `OKFDocument.parse()` accepts the bytes (it takes the text only).
|
||||
2. The values arrive as the shapes we intend: `generated` a mapping, `sources` a list of mappings, and our `x-` fields
|
||||
as the types `docs/x-fields.md` gives them. Record the type each value arrives as, not only that it parsed.
|
||||
3. `validate()` passes. It checks one key (`type`), so a green `validate()` alone is not "upstream accepts the page".
|
||||
4. Upstream's semantic readers (`trust_tier`, `normalize_verified`, `is_stale`) run over the frontmatter mapping, not
|
||||
the document, without raising.
|
||||
|
||||
**A clean sweep is worth nothing until the harness is shown able to fail:** feed it a page with `type: [unclosed` and
|
||||
confirm it raises before you report the zeroes. Google's viewer is the second outside reader: criterion 5 requires it
|
||||
to read every collection without an error.
|
||||
|
||||
## Step 4: classify the diff
|
||||
|
||||
From the spec's own "Changes from vN" section plus the evidence of steps 3 and 3a, put every change in one class:
|
||||
|
||||
- **Breaking:** name it, and measure our exposure in step 5.
|
||||
- **Additive:** new optional fields, new conventional headings.
|
||||
- **Deferred upstream:** a format specified but its runtime left to a later revision. Out of scope on upstream's
|
||||
deferral, not on our preference.
|
||||
- **Observed but undocumented:** present in an official bundle, absent from the spec sections read. Recorded as open;
|
||||
never promoted silently to another class.
|
||||
- **Tightened in place, no version bump:** the text narrows what a key may hold under the same version number. A value
|
||||
that conformed last round does not conform now, so "conformant with v0.2" must name the spec commit too.
|
||||
|
||||
## Step 5: measure our exposure
|
||||
|
||||
For every change the diff touches, search the code that writes and checks pages and cite `file:line`: the auditor
|
||||
(`okfwiki/audit.py`), the assembly and link code (`okfwiki/kassemble.py`, `okfwiki/klink.py`), the skill
|
||||
(`skills/okf-wiki/SKILL.md`), the `x-` field list (`docs/x-fields.md`), the gates under `gates/` and their cases under
|
||||
`gates-local/`. Never reason about a key set; measure it.
|
||||
|
||||
Where upstream now has a standard field for something we carry in an `x-` field, the `x-` field moves to it
|
||||
(`CLAUDE.md` § The standard). That is a format change: it is proposed to the operator with the measurement, and it is
|
||||
his decision.
|
||||
|
||||
There are no consumers of this repository yet (R33 is dropped). When something depends on `okf-wiki`, add a step
|
||||
here that tells each consumer what changed and lets them measure their own exposure.
|
||||
|
||||
## Step 6: move the pin
|
||||
|
||||
Only after steps 1 to 5 are written down:
|
||||
|
||||
1. Change `PIN` in `tools/upstream_watch.py` and the test that holds it (`tests/test_upstream_watch.py`), test first.
|
||||
2. Run the three test suites, `mypy --strict`, the mutant gate (`gates/README.md`) and the check against Google's
|
||||
viewer, and record the numbers.
|
||||
3. Write the pinned commit, the classified diff, the measured exposure and every correction in `PLAN.md § Logg`. A
|
||||
claim withdrawn is only safely withdrawn where the claim was written.
|
||||
|
||||
Moving the pin resets what the morning job counts as already announced, because everything behind the new pin has
|
||||
been absorbed.
|
||||
|
||||
## What the morning job cannot see
|
||||
|
||||
- **Meaning.** When upstream tightened v0.2 in place, a watch on `SPEC.md` fires correctly, but no commit list says "a
|
||||
value that conformed last month does not conform now". The message therefore always says "run the runbook", never
|
||||
"here is your exposure".
|
||||
- **A silent relocation.** The last move of the repository was announced in a `README.md` commit, which is why
|
||||
`README.md` is not on the quiet list. A move announced anywhere else is invisible to the job.
|
||||
- **A tightening with no commit:** a changed reference implementation shipped elsewhere, or errata outside the
|
||||
repository. Reading upstream, as this runbook does, is the only cover.
|
||||
|
||||
The job narrows the window between an upstream change and our noticing it. It does not close it: a quiet morning is not
|
||||
proof that upstream is unchanged.
|
||||
37
docs/x-fields.md
Normal file
37
docs/x-fields.md
Normal file
|
|
@ -0,0 +1,37 @@
|
|||
# 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.
|
||||
Loading…
Add table
Add a link
Reference in a new issue