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

72 lines
18 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 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