# 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 | awk -F/ '{print $1}' | sort -u # top-level entries git ls-tree -r --name-only | 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.