okf-wiki/docs/rule-decisions.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

18 KiB
Raw Blame History

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