okl 0.8.9

The retrieval work since 0.8.8, each step measured and most of it shipped off: a relevance
floor before the cutoff, a symptom and aliases on every advice record, an optional semantic
arm, and three arms that stay experiments (an index of every lesson, the near misses, a
cross-encoder second stage); hygiene metrics; the measured claims re-checked against their
receipts; the short README with the essays in docs/.

• A cross-encoder second stage, measured and shipped off (#258, REPORT §4t). okl check --rerank runs a local ONNX cross-encoder (Xenova/ms-marco-MiniLM-L-6-v2, installed with the new rerank extra, cached once by okl embed) over the first 24 candidates (fused when --hybrid is on) on each record's title, symptom and aliases, and reorders them before the gates; "rerank": true in the config or OKL_RERANK=1 turns it on for every check, the service's check request carries it, each briefed record carries its rerank_score, and without the extra or the model the first-stage order stands and the JSON says why. The model was chosen from five local cross-encoders, and the static embedder kept against five contextual ones, on a selection set that is not the held-out set (receipts rerank-select-20261023.txt, embedder-select-20261023.txt). Measured by the probe at one commit against one store: one more held-out paraphrase of eight and one held-out bug report fewer, one of the probe's own tickets fewer, the precision prompts' counts unchanged, about 0.5 s a check with the model loaded. The pre-registered falsifier fired, so the stage ships as an experiment flag, off. The probe gains --rerank and prints the median check latency; evals/rerank_select.py, evals/rerank_spike.py and evals/embedder_select.py are the selection scripts.
• okl check --near-misses: the records that matched the task and were left out, by the floor or the cutoff, as id and title, at most twelve lines. Off by default. The pre-flight in REPORT §4s showed it could name the governing lesson in 3 of the 10 held-out tasks the briefing misses, on tasks where the briefed arm already reproduced nothing, and that the other 7 are not in the full-text candidate window at all; so no live run, and the harness's nearmiss arm stays for a later instrument.
• The index arm, as an experiment (#258, REPORT §4r). okl check --index appends every other live lesson in scope as id and title with one line telling the agent to okl show a relevant one before writing code; the service and client carry the flag. The A/B harness gains --arms baseline,briefed,indexed, a GENERATOR_TOOLS setting that lets claude -p run okl show through a logging shim, per-sample fetch records in the receipt, and evals/heldout_tasks.jsonl (24 blind rephrasings as harness tasks). Measured (REPORT §4r, receipt ab-20261023-1303): given about 300 titles and an instruction to read a relevant one, the agent fetched the governing lesson once in 71 samples, so the arm stays an experiment and the hook gains no index; the harness pieces stay for the next variant. Pre-flight now gates the task file the run executes, and the fetch log counts only a successful okl show. The doc-init-flags rule's check is ci/check-init-flags.py, which also reads the guide's prose.
• An optional semantic arm beside the full-text search, measured and not made the default (#258, step 3). okl embed writes one vector per record from a local static embedding model (minishlab/potion-retrieval-32M, installed with the new hybrid extra, downloaded once); okl check --hybrid fuses the nearest records with the full-text candidates (linear, a convex combination, or rrf), and a candidate whose cosine reaches 0.40 passes the relevance floor by meaning; "hybrid": "linear" in the config or OKL_HYBRID turns it on for every check. At check time the model loads from the local cache only, so a hook never reaches the network, and without the extra, the model or the vectors the briefing is the full-text one and the JSON says why. Measured with no paid model call (REPORT §4q): one more held-out paraphrase of eight found, nothing on tickets or bug reports, one record more on two of six short prompts, 0.8 s per prompt for the model load; a first pass at a 0.25 line and with any semantic candidate subject to the word rules is recorded and was revised. The vector search is a numpy matrix product (3 ms at 50,000 records); the ADR carries the amendment and the next tier. New: evals/hybrid_grid.py and its receipt, evals/probe_rephrase.py --hybrid.
• Lessons carry aliases: the words a developer uses when one bites (#258, the second vectorless arm). A record may carry a "; "-separated list of phrases ("logged out on refresh; session lost"), indexed with the symptom at its weight in SQLite and Postgres (an older store rebuilds its index once on open); its words count toward the relevance floor's two shared words, and a one-word alias matched whole counts as the record's subject. okl record --alias (repeatable), okl update --alias (an empty value clears), okl show, the MCP tools, the service and seed packs (a JSON list) carry the field. All 136 org-scoped Rules, Defects and Gates in the seed packs gained two to eight aliases, written from each record's own content. Measured with no model (REPORT §4p): on a held-out set of 24 rephrasings written blind from the eval tasks, ticket 6→7, paraphrase 2→3, bug report 5→5 of 8; the probe's own bug-report row 3→8 and paraphrase 0→1 (sentences the author had read); the six short precision prompts unchanged on seeded stores; every governing lesson kept. A first pass in which any alias word counted as a record's subject answered a short prompt with twelve records again and was revised before shipping. New: evals/compare_seed_briefings.py (two seed trees, eight briefings, held-out recall and precision before and after), evals/heldout_variants.json, evals/probe_prompts.json.
• The measured claims match every committed receipt, after an independent verification (2026-10-22). The README and REPORT §2b put the noise floor at 21 points or more (two runs of §4m's instrument; 26 points across the §4j boundary), where both still said 17; two tasks, not three, have never reproduced unbriefed, and the rate limiter's counts are quoted from the receipts (1 of 41 unbriefed, 2 of 44 briefed), with a test that recomputes the sentence. REPORT §5 finding 7 recuts its pool to the seven runs through §4h (68 of 163 against 11 of 164, the same 42% against 7%), reports §4i's run beside it with the eight-run figure the launch posts quoted, since §4i pre-registered the layout change as a new series, and names the three smoke receipts outside the pool; the README, the anatomy sheet and the docs quote the seven-run pool; §4n says what its identity test covers. evals/preflight.py reads OKL_BRIEF_INTERESTS as the harness does, so the gate checks the briefing the run will use (receipts 1323 through 2254 ran filtered past an unfiltered gate, with react_fetch's rule absent from the arm), with a test. docs/RELATED-WORK.md gives ContextCov its fourth, model-judged module, states Memory Transfer Learning's trajectory finding as the paper does, and scopes its "leaves open" claims to the seven papers read (#264).
• The A/B harness refuses a run whose working tree moved. It records HEAD when a run starts and again when it writes the receipt; a difference marks the receipt working_tree_moved and not usable, with both commits named, because the briefed arm renders from the checkout and a branch switch mid-run briefs the later samples with other code (REPORT §4o).
• Every advice record gets a symptom, and okl seed says when one is missing (#258, step 2). A prompt that describes what went wrong finds a lesson through its symptom; twenty org Rules, Defects and Gates in the seed packs had none and were reachable only by a prompt that used their title's words. Each now has one, written in the words a developer would use when it bites. okl seed prints one line per file naming the records that lack a symptom (the same hygiene pass that warns on trace-shaped and over-scoped records), and the load-your-rules guide carries the authoring rule.
• A relevance floor before the top-12 cutoff (#257). The search is an OR of the task's subject words, so a short or generic prompt used to fill every slot with records sharing one word with it. A record is now briefed only when it shares two subject words with the task, or one that is in its title or symptom, or one when the task has only one word; a record below the floor stays when it links one step to a kept one. What the floor left out is counted (weak_matches), each briefed record names its matched_terms in the JSON, and both the briefing and the hook's one-line notice say when nothing matched closely. The pipeline diagram gains the stage.
• Hygiene: stale-use and over-scope, reported and warned about (#252, #255). The exposure log now keeps which briefed lessons the briefing marked as changed since their last check (a new drifted_ids column; older rows read as none), and the client logs after the drift marks rather than before. okl metric gains a hygiene block: stale-use (briefings that included such a lesson, over the briefings logged) and over-scope (live org lessons whose title, symptom or fix names one repository's world), each with its denominator and the lessons it flags, plus a count of trace-shaped org lessons; --format json carries it, and the service serves it at /metric/hygiene. okl seed prints the same two findings as warnings before importing, and --strict exits 2 instead, for CI on a ledger repo. One detector module (okl.hygiene) feeds both, so the metric and the warning cannot disagree.
• Docs: docs/RELATED-WORK.md, a dated page with one row per 2026 paper on memory for coding agents: what each measured, with figures read from the PDFs, and where okl stands beside it. Linked from the README's "How okl differs" section. Products stay out of it on purpose.
• The README is a short version again, and says what okl is in its readers' terms. It
  opens with the install line and the measured figure, puts a what-goes-wrong-and-what-catches-it
  table and a which-agent-which-part table in text (the six cards used to live only inside the
  overview image), states how okl differs in four lines, and ends with questions. The essays
  moved to docs/ with their content intact: where this sits, verification, design choices,
  costs and knobs, what okl init writes, every command, subagents, seeding, the scaffold and
  the shared service. One noun throughout: a lesson. Every sentence a test or a drift rule
  pins (the corpus count, the token costs and their receipt, the reproduced-defect list, the
  install line, the init flags) is unchanged.
• okl describes itself as verified memory for coding agents, and the loop that keeps it
  true (#235): the README headline, the PyPI and MCP Registry descriptions, the plugin and
  CLI descriptions, and the overview and anatomy sheets, which are re-rendered.
  docs/overview/render_linkedin.py is the recipe for the 4:5 feed cut of the anatomy.