org-knowledge-layer 0.4.1__tar.gz → 0.5.0__tar.gz

{org_knowledge_layer-0.4.1/src/okl/scaffold → org_knowledge_layer-0.5.0/.claude}/hooks/userpromptsubmit-okl-check.sh

@@ -36,8 +36,10 @@ resolve_okl() {
 if ! OKL=$(resolve_okl); then
   [ "${OKL_OFFLINE:-0}" = "1" ] && exit 0
   echo "okl NOT FOUND — blocking (a check that can't run must not pass as clean)." >&2
-  echo "Install it (pip install okl), set OKL_BIN, or re-run 'okl init' from a shell where it" >&2
-  echo "works (pins okl_bin into .okl/config.json). OKL_OFFLINE=1 proceeds without the layer." >&2
+  echo "Install it: pip install org-knowledge-layer. NOT 'pip install okl' — PyPI refuses that" >&2
+  echo "name as confusable, so it fails and looks like the tool does not exist." >&2
+  echo "Or set OKL_BIN, or re-run 'okl init' from a shell where okl works (that pins okl_bin" >&2
+  echo "into .okl/config.json). OKL_OFFLINE=1 proceeds without the layer." >&2
   exit 2
 fi
 

{org_knowledge_layer-0.4.1 → org_knowledge_layer-0.5.0}/.gitignore

@@ -19,3 +19,5 @@ e2e/
 
 #Ignore vscode AI rules
 .github/instructions/codacy.instructions.md
+okl.db-wal
+okl.db-shm

{org_knowledge_layer-0.4.1 → org_knowledge_layer-0.5.0}/AGENTS.md

@@ -9,7 +9,14 @@ The hooks fire on your own session: `UserPromptSubmit` injects the store's brief
 your context before you start; `Stop` blocks your first stop to ask what was learned.
 Answer it honestly — record with a deliberate scope (`org` spreads to every repo,
 `repo` stays local) and tags from the closed vocabulary in `store.KNOWN_TAGS`. Growing
-that vocabulary is an edit to the set plus a note in the tags ADR, never an ad-hoc tag.
+that vocabulary is a deliberate act, never an ad-hoc tag: `okl record --type Vocabulary
+--scope org --title <tag>` declares one for THIS store (a Go or Rust team needs no fork),
+and editing `KNOWN_TAGS` changes the floor every store ships with.
+
+- **`applies_to` is where a lesson is TRUE; tags are where it was FOUND.** Leave it unset
+  unless the lesson is false or meaningless off that stack — unset reaches every repo and
+  is the safe default, while a wrong value hides the record silently. Never derive it from
+  a tag: that is the reverted §4d defect, which measured worse than no filter at all.
 
 - **Verification is evidence-based**: `okl verify <id> --run "<check>" --expect "<signal>"`.
   Never re-record with `--verified` to clear drift — run the check.

{org_knowledge_layer-0.4.1 → org_knowledge_layer-0.5.0}/CHANGELOG.md

@@ -1,5 +1,41 @@
 # Changelog
 
+## 0.5.0
+
+### The vocabulary is no longer fixed in the package
+
+- **A store can declare its own subject tags.** `KNOWN_TAGS` remains, but as the *floor*
+  every store ships with rather than the whole vocabulary. Widen it by recording a
+  `Vocabulary` node, whose title is the tag:
+
+  ```bash
+  okl record --type Vocabulary --scope org --title rust --body "Rust services."
+  okl record --type Rule --scope org --tags rust --title "Prefer ? over unwrap in handlers"
+  ```
+
+  Before this, a Go, Rust or PowerShell team could not file a lesson under its own language
+  without forking the package, which is a hard stop on adoption for a tool whose claim is
+  that a lesson learned in one place reaches another. What the closed vocabulary was *for*
+  survives: it catches the typo that files a record where nobody looks, and closed-per-store
+  still does, so `rustt` is refused in a store that declared `rust`. What changes is who may
+  grow it. `STACK_TAGS`, which gates `applies_to`, is deliberately not extended.
+
+- **`frontend` and `prose` added to the floor.** Neither is specific to one org: any repo
+  that renders markup has frontend lessons, and any repo that governs its writing has prose
+  ones. `react` was the nearest existing tag for the first and is wrong, being a stack tag.
+
+### Fixed
+
+- **The hooks no longer tell you to run `pip install okl`, which cannot work.** PyPI refuses
+  `okl` as confusable, so the distribution is `org-knowledge-layer` and `okl` is only the
+  console script. The wrong name was in the `UserPromptSubmit` hook's not-found message,
+  which fires *exactly* when someone has no working install and sent them to a 404 that
+  reads as "this tool was never published." `okl init` stamps that hook into every repo it
+  touches, so the error propagated with adoption. Re-run `okl init` to pick up the new file.
+- `cli.py`'s MCP hint said `pip install okl[mcp]`; now `pip install 'org-knowledge-layer[mcp]'`,
+  quoted because zsh globs unquoted brackets.
+
+
 ## 0.4.1
 
 ### Security — affects the CI workflow already in your repo

{org_knowledge_layer-0.4.1 → org_knowledge_layer-0.5.0}/CLAUDE.md

@@ -9,7 +9,14 @@ The hooks fire on your own session: `UserPromptSubmit` injects the store's brief
 your context before you start; `Stop` blocks your first stop to ask what was learned.
 Answer it honestly — record with a deliberate scope (`org` spreads to every repo,
 `repo` stays local) and tags from the closed vocabulary in `store.KNOWN_TAGS`. Growing
-that vocabulary is an edit to the set plus a note in the tags ADR, never an ad-hoc tag.
+that vocabulary is a deliberate act, never an ad-hoc tag: `okl record --type Vocabulary
+--scope org --title <tag>` declares one for THIS store (a Go or Rust team needs no fork),
+and editing `KNOWN_TAGS` changes the floor every store ships with.
+
+- **`applies_to` is where a lesson is TRUE; tags are where it was FOUND.** Leave it unset
+  unless the lesson is false or meaningless off that stack — unset reaches every repo and
+  is the safe default, while a wrong value hides the record silently. Never derive it from
+  a tag: that is the reverted §4d defect, which measured worse than no filter at all.
 
 - **Verification is evidence-based**: `okl verify <id> --run "<check>" --expect "<signal>"`.
   Never re-record with `--verified` to clear drift — run the check.

{org_knowledge_layer-0.4.1 → org_knowledge_layer-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: org-knowledge-layer
-Version: 0.4.1
+Version: 0.5.0
 Summary: Org Knowledge Layer — an installable sixth surface that carries encoded engineering lessons across repos.
 Author: Joshua Dell
 License: MIT
@@ -19,7 +19,7 @@ Requires-Dist: httpx>=0.27; extra == 'dev'
 Requires-Dist: mypy==2.3.1; extra == 'dev'
 Requires-Dist: pydantic>=2; extra == 'dev'
 Requires-Dist: pytest-cov==7.1.0; extra == 'dev'
-Requires-Dist: pytest==8.4.2; extra == 'dev'
+Requires-Dist: pytest==9.1.1; extra == 'dev'
 Requires-Dist: ruff==0.16.5; extra == 'dev'
 Requires-Dist: uvicorn>=0.29; extra == 'dev'
 Provides-Extra: mcp
@@ -210,6 +210,20 @@ with receipts, not a benchmark.
 
 <img src="docs/okl-how-it-works.svg" alt="One repo records a lesson; every other repo is briefed on it before its next task. The store is typed, scoped and tagged; every verification stamp carries the check that earned it." width="100%">
 
+### How a briefing is actually built
+
+`okl check` is a retrieval pipeline: seven stages turn a task sentence and the whole corpus
+into the twelve records an agent reads. Two stages can drop a record, and only one of them
+is entitled to — the distinction that this project got wrong once and measured its way out
+of ([REPORT §4d](evals/REPORT.md)).
+
+<img src="docs/okl-retrieval-pipeline.svg" alt="Seven stages: the corpus, a BM25 fetch of three times the limit, a scope gate, the exclusive applies_to filter, the inclusive tags-times-interests filter, a top-12 cutoff, bucketing by type, and rendering. Each stage shows how many records survive it." width="100%">
+
+Every count in that diagram is **traced**, not transcribed — `docs/render_pipeline_diagram.py`
+runs the real `store.search` and `core._in_scope` against a store seeded from `seed/`, and
+`test_pipeline_diagram_is_current` fails if the committed render is not what the generator
+produces today. Change a BM25 weight or a filter predicate and the diagram goes red with it.
+
 ### The mental model
 
 `okl` stores small, typed **notes** and the **links** between them.

{org_knowledge_layer-0.4.1 → org_knowledge_layer-0.5.0}/README.md

@@ -176,6 +176,20 @@ with receipts, not a benchmark.
 
 <img src="docs/okl-how-it-works.svg" alt="One repo records a lesson; every other repo is briefed on it before its next task. The store is typed, scoped and tagged; every verification stamp carries the check that earned it." width="100%">
 
+### How a briefing is actually built
+
+`okl check` is a retrieval pipeline: seven stages turn a task sentence and the whole corpus
+into the twelve records an agent reads. Two stages can drop a record, and only one of them
+is entitled to — the distinction that this project got wrong once and measured its way out
+of ([REPORT §4d](evals/REPORT.md)).
+
+<img src="docs/okl-retrieval-pipeline.svg" alt="Seven stages: the corpus, a BM25 fetch of three times the limit, a scope gate, the exclusive applies_to filter, the inclusive tags-times-interests filter, a top-12 cutoff, bucketing by type, and rendering. Each stage shows how many records survive it." width="100%">
+
+Every count in that diagram is **traced**, not transcribed — `docs/render_pipeline_diagram.py`
+runs the real `store.search` and `core._in_scope` against a store seeded from `seed/`, and
+`test_pipeline_diagram_is_current` fails if the committed render is not what the generator
+produces today. Change a BM25 weight or a filter predicate and the diagram goes red with it.
+
 ### The mental model
 
 `okl` stores small, typed **notes** and the **links** between them.

{org_knowledge_layer-0.4.1 → org_knowledge_layer-0.5.0}/docs/decisions/2026-07-21-subject-tags-controlled-vocabulary.md

@@ -57,3 +57,44 @@ seed-file comments ("eval-integrity lessons are org-scoped") and the scaffold's
   pipeline, not a language. The distinction the vocabulary already draws (stacks vs subjects)
   did not have a slot for "the language this is written in", and adding one is cheaper than
   overloading a stack tag whose meaning other repos depend on.
+- 2026-09-03: **the "revisit when" condition above was met, and the vocabulary is now
+  extensible per store.** `KNOWN_TAGS` remains, but as the *floor* every store ships with
+  rather than the whole vocabulary: a store widens it by recording `Vocabulary` nodes,
+  whose title is the tag, and `Store.add_node` validates against floor ∪ declared.
+
+  The trigger was a language-support audit. Everything else in okl is language-agnostic —
+  drift asks git about path globs, verification runs whatever command you hand it, the
+  store holds text — and a Rust repo was driven end to end successfully except for one
+  thing: `okl record --tags rust` was refused, and the only remedy was to fork the package.
+  That is a hard stop on adoption for a tool whose whole claim is that a lesson learned in
+  one place reaches another.
+
+  What the closed vocabulary was *for* survives intact. It exists to catch the typo that
+  files a record where nobody looks, and closed-per-store still does: `rustt` is refused in
+  a store that declared `rust`. What changes is who is entitled to grow it — the org that
+  owns the store, rather than whoever can merge to this package.
+
+  A `Vocabulary` node is validated against the floor only. Otherwise the first declaration
+  in a fresh store would require the tag it is declaring.
+
+  **Not extended:** `STACK_TAGS`, which gates `applies_to`. Declaring `rust` makes it usable
+  as a subject tag, not as an applicability value. That is a narrower and rarer need — it
+  only matters for a lesson that is genuinely false off-stack — and §4h measured that the
+  filter `applies_to` feeds changes 0% of delivered briefing slots today. Extending the
+  exclusive mechanism without a measurement is exactly what §4d punished.
+- 2026-09-17: `frontend` and `prose` added **to the floor**, when `emeraldleaf-dev` joined
+  the layer and every one of its records was rejected: markup and CSS defects, and rules
+  about writing. `react` was the nearest existing tag for the first group and is wrong for
+  the same reason `python-rag` was wrong for `python`. It is a stack tag, and that repo is a
+  hand-rolled Astro site with no UI framework. `frontend` names the subject those lessons are
+  actually about: markup whitespace semantics, CSS layout and responsive behaviour, browser
+  rendering. `prose` had no near-miss at all. Writing is governed in these repos the way code
+  is, with an em-dash budget and a claims-must-be-supported rule behind mechanical gates, and
+  a rule with a gate behind it is a rule the layer should carry.
+
+  The floor rather than a per-store `Vocabulary` declaration, now that the amendment above
+  makes both available. Neither tag is specific to one org: any repo that renders markup has
+  frontend lessons, and any repo that governs its writing has prose ones. The floor is for
+  subjects every store would otherwise have to declare for itself, which is the same reason
+  `messaging` and `python` are in it. Per-store declaration is for what an org's own stack
+  needs and nobody else's.

org_knowledge_layer-0.5.0/docs/okl-retrieval-pipeline.svg

@@ -0,0 +1,89 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="980" height="994" viewBox="0 0 980 994" font-family="ui-sans-serif,-apple-system,Segoe UI,Helvetica,Arial,sans-serif">
+<rect width="980" height="994" fill="#F5F3F0"/>
+<text x="28" y="46" font-size="27" font-weight="700" fill="#1E1B18">How an okl briefing gets built</text>
+<text x="28" y="72" font-size="14" fill="#4E4740">161 records and one task sentence become the 12 an agent reads. Two stages can drop a record; only one is entitled to.</text>
+<text x="28" y="96" font-size="11.5" font-family="ui-monospace,SFMono-Regular,Menlo,Consolas,monospace" fill="#7C736A">GENERATED from the live pipeline - docs/render_pipeline_diagram.py</text>
+<text x="28" y="112" font-size="11.5" font-family="ui-monospace,SFMono-Regular,Menlo,Consolas,monospace" fill="#7C736A">traced task: "Add an endpoint that returns a single order by id for the signed-in user."</text>
+<text x="28" y="128" font-size="11.5" font-family="ui-monospace,SFMono-Regular,Menlo,Consolas,monospace" fill="#7C736A">repo interests: python, method, security, agent-safety, retrieval-design, eval-integrity, data-quality</text>
+<rect x="28" y="154" width="924" height="90" fill="#FFFFFF" stroke="#DCD6CE"/>
+<rect x="28" y="154" width="74" height="90" fill="#EBE7E1" stroke="#DCD6CE"/>
+<text x="65" y="192" font-size="26" font-weight="700" fill="#B4531F" font-family="ui-monospace,SFMono-Regular,Menlo,Consolas,monospace" text-anchor="middle">0</text>
+<text x="65" y="210" font-size="9" fill="#7C736A" font-family="ui-monospace,SFMono-Regular,Menlo,Consolas,monospace" text-anchor="middle" letter-spacing="1">STORE</text>
+<text x="120" y="179" font-size="15" font-weight="600" fill="#1E1B18">The corpus</text>
+<text x="120" y="198" font-size="12" fill="#4E4740">Every record carries scope (permission), tags (subject), applies_to (validity) and files</text>
+<text x="120" y="213" font-size="12" fill="#4E4740">(what it governs). Nothing is ranked yet.</text>
+<text x="120" y="224" font-size="11.5" font-family="ui-monospace,SFMono-Regular,Menlo,Consolas,monospace" fill="#1E1B18" font-weight="500">161 records</text>
+<rect x="120" y="230" width="818" height="9" rx="2" fill="#EBE7E1"/><rect x="120" y="230" width="818" height="9" rx="2" fill="#B4531F"/>
+<rect x="28" y="250" width="924" height="90" fill="#FFFFFF" stroke="#DCD6CE"/>
+<rect x="28" y="250" width="74" height="90" fill="#EBE7E1" stroke="#DCD6CE"/>
+<text x="65" y="288" font-size="26" font-weight="700" fill="#B4531F" font-family="ui-monospace,SFMono-Regular,Menlo,Consolas,monospace" text-anchor="middle">1</text>
+<text x="65" y="306" font-size="9" fill="#7C736A" font-family="ui-monospace,SFMono-Regular,Menlo,Consolas,monospace" text-anchor="middle" letter-spacing="1">RANK</text>
+<text x="120" y="275" font-size="15" font-weight="600" fill="#1E1B18">Fetch 3x more candidates than needed</text>
+<text x="120" y="294" font-size="12" fill="#4E4740">SQLite FTS5, weighted title x8, body x4, symptom x4, fix x2. Tags are NOT indexed - a tag</text>
+<text x="120" y="309" font-size="12" fill="#4E4740">can get a record excluded, never help it be found.</text>
+<text x="120" y="320" font-size="11.5" font-family="ui-monospace,SFMono-Regular,Menlo,Consolas,monospace" fill="#1E1B18" font-weight="500">36 fetched</text>
+<text x="938" y="320" font-size="11.5" font-family="ui-monospace,SFMono-Regular,Menlo,Consolas,monospace" fill="#7C736A" text-anchor="end">limit x 3</text>
+<rect x="120" y="326" width="818" height="9" rx="2" fill="#EBE7E1"/><rect x="120" y="326" width="818" height="9" rx="2" fill="#B4531F"/>
+<rect x="28" y="346" width="924" height="90" fill="#FFFFFF" stroke="#DCD6CE"/>
+<rect x="28" y="346" width="74" height="90" fill="#EBE7E1" stroke="#DCD6CE"/>
+<text x="65" y="384" font-size="26" font-weight="700" fill="#B4531F" font-family="ui-monospace,SFMono-Regular,Menlo,Consolas,monospace" text-anchor="middle">2</text>
+<text x="65" y="402" font-size="9" fill="#7C736A" font-family="ui-monospace,SFMono-Regular,Menlo,Consolas,monospace" text-anchor="middle" letter-spacing="1">SCOPE</text>
+<text x="120" y="371" font-size="15" font-weight="600" fill="#1E1B18">Permission - who may see this</text>
+<text x="120" y="390" font-size="12" fill="#4E4740">A repo's own records pass first and unconditionally. org records continue. Another repo's</text>
+<text x="120" y="405" font-size="12" fill="#4E4740">records stop here: the curation boundary.</text>
+<text x="938" y="371" font-size="9.5" fill="#9B3B3B" font-family="ui-monospace,SFMono-Regular,Menlo,Consolas,monospace" font-weight="700" text-anchor="end" letter-spacing="0.8">DROPS</text>
+<text x="120" y="416" font-size="11.5" font-family="ui-monospace,SFMono-Regular,Menlo,Consolas,monospace" fill="#1E1B18" font-weight="500">33 survive</text>
+<text x="938" y="416" font-size="11.5" font-family="ui-monospace,SFMono-Regular,Menlo,Consolas,monospace" fill="#7C736A" text-anchor="end">3 dropped: other repos</text>
+<rect x="120" y="422" width="818" height="9" rx="2" fill="#EBE7E1"/><rect x="120" y="422" width="750" height="9" rx="2" fill="#B4531F"/><rect x="870" y="422" width="68" height="9" rx="2" fill="#9B3B3B" opacity="0.4"/>
+<rect x="28" y="442" width="924" height="90" fill="#FFFFFF" stroke="#DCD6CE"/>
+<rect x="28" y="442" width="74" height="90" fill="#EBE7E1" stroke="#DCD6CE"/>
+<text x="65" y="480" font-size="26" font-weight="700" fill="#B4531F" font-family="ui-monospace,SFMono-Regular,Menlo,Consolas,monospace" text-anchor="middle">3</text>
+<text x="65" y="498" font-size="9" fill="#7C736A" font-family="ui-monospace,SFMono-Regular,Menlo,Consolas,monospace" text-anchor="middle" letter-spacing="1">VALID</text>
+<text x="120" y="467" font-size="15" font-weight="600" fill="#1E1B18">applies_to - the only filter allowed to exclude</text>
+<text x="120" y="486" font-size="12" fill="#4E4740">EXCLUSIVE. Set by hand on 31 of 161 records, only where a lesson is false off-stack. Unset</text>
+<text x="120" y="501" font-size="12" fill="#4E4740">means anywhere, which is why it is safe.</text>
+<text x="938" y="467" font-size="9.5" fill="#9B3B3B" font-family="ui-monospace,SFMono-Regular,Menlo,Consolas,monospace" font-weight="700" text-anchor="end" letter-spacing="0.8">DROPS</text>
+<text x="120" y="512" font-size="11.5" font-family="ui-monospace,SFMono-Regular,Menlo,Consolas,monospace" fill="#1E1B18" font-weight="500">29 survive</text>
+<text x="938" y="512" font-size="11.5" font-family="ui-monospace,SFMono-Regular,Menlo,Consolas,monospace" fill="#7C736A" text-anchor="end">4 dropped: off-stack</text>
+<rect x="120" y="518" width="818" height="9" rx="2" fill="#EBE7E1"/><rect x="120" y="518" width="659" height="9" rx="2" fill="#B4531F"/><rect x="779" y="518" width="91" height="9" rx="2" fill="#9B3B3B" opacity="0.4"/>
+<rect x="28" y="538" width="924" height="90" fill="#FFFFFF" stroke="#DCD6CE"/>
+<rect x="28" y="538" width="74" height="90" fill="#EBE7E1" stroke="#DCD6CE"/>
+<text x="65" y="576" font-size="26" font-weight="700" fill="#B4531F" font-family="ui-monospace,SFMono-Regular,Menlo,Consolas,monospace" text-anchor="middle">4</text>
+<text x="65" y="594" font-size="9" fill="#7C736A" font-family="ui-monospace,SFMono-Regular,Menlo,Consolas,monospace" text-anchor="middle" letter-spacing="1">SUBJECT</text>
+<text x="120" y="563" font-size="15" font-weight="600" fill="#1E1B18">tags x interests - one shared subject is enough</text>
+<text x="120" y="582" font-size="12" fill="#4E4740">INCLUSIVE. Untagged always passes. The exclusive version was reverted (REPORT 4d): it hid 35</text>
+<text x="120" y="597" font-size="12" fill="#4E4740">of 172 records and the briefed arm then reproduced a defect it dropped.</text>
+<text x="938" y="563" font-size="9.5" fill="#4A6B3D" font-family="ui-monospace,SFMono-Regular,Menlo,Consolas,monospace" font-weight="700" text-anchor="end" letter-spacing="0.8">ANY-MATCH</text>
+<text x="120" y="608" font-size="11.5" font-family="ui-monospace,SFMono-Regular,Menlo,Consolas,monospace" fill="#1E1B18" font-weight="500">21 survive</text>
+<text x="938" y="608" font-size="11.5" font-family="ui-monospace,SFMono-Regular,Menlo,Consolas,monospace" fill="#7C736A" text-anchor="end">8 dropped: no shared subject</text>
+<rect x="120" y="614" width="818" height="9" rx="2" fill="#EBE7E1"/><rect x="120" y="614" width="477" height="9" rx="2" fill="#B4531F"/><rect x="597" y="614" width="182" height="9" rx="2" fill="#9B3B3B" opacity="0.4"/>
+<rect x="28" y="634" width="924" height="90" fill="#FFFFFF" stroke="#DCD6CE"/>
+<rect x="28" y="634" width="74" height="90" fill="#EBE7E1" stroke="#DCD6CE"/>
+<text x="65" y="672" font-size="26" font-weight="700" fill="#B4531F" font-family="ui-monospace,SFMono-Regular,Menlo,Consolas,monospace" text-anchor="middle">5</text>
+<text x="65" y="690" font-size="9" fill="#7C736A" font-family="ui-monospace,SFMono-Regular,Menlo,Consolas,monospace" text-anchor="middle" letter-spacing="1">CUTOFF</text>
+<text x="120" y="659" font-size="15" font-weight="600" fill="#1E1B18">Top 12, and the rest are counted not hidden</text>
+<text x="120" y="678" font-size="12" fill="#4E4740">Full-text matching is permissive enough that a plausible task matches most of a mature</text>
+<text x="120" y="693" font-size="12" fill="#4E4740">store. The number discarded travels with the result.</text>
+<text x="938" y="659" font-size="9.5" fill="#9B3B3B" font-family="ui-monospace,SFMono-Regular,Menlo,Consolas,monospace" font-weight="700" text-anchor="end" letter-spacing="0.8">TRUNCATES</text>
+<text x="120" y="704" font-size="11.5" font-family="ui-monospace,SFMono-Regular,Menlo,Consolas,monospace" fill="#1E1B18" font-weight="500">12 delivered</text>
+<text x="938" y="704" font-size="11.5" font-family="ui-monospace,SFMono-Regular,Menlo,Consolas,monospace" fill="#7C736A" text-anchor="end">9 reported as trimmed</text>
+<rect x="120" y="710" width="818" height="9" rx="2" fill="#EBE7E1"/><rect x="120" y="710" width="273" height="9" rx="2" fill="#B4531F"/><rect x="393" y="710" width="204" height="9" rx="2" fill="#9B3B3B" opacity="0.4"/>
+<rect x="28" y="730" width="924" height="90" fill="#FFFFFF" stroke="#DCD6CE"/>
+<rect x="28" y="730" width="74" height="90" fill="#EBE7E1" stroke="#DCD6CE"/>
+<text x="65" y="768" font-size="26" font-weight="700" fill="#B4531F" font-family="ui-monospace,SFMono-Regular,Menlo,Consolas,monospace" text-anchor="middle">6</text>
+<text x="65" y="786" font-size="9" fill="#7C736A" font-family="ui-monospace,SFMono-Regular,Menlo,Consolas,monospace" text-anchor="middle" letter-spacing="1">SHAPE</text>
+<text x="120" y="755" font-size="15" font-weight="600" fill="#1E1B18">Bucket by type, then route to imperatives</text>
+<text x="120" y="774" font-size="12" fill="#4E4740">Eight buckets: gates, defects, retractions, tombstones, threat prior-art, rules, vocabulary,</text>
+<text x="120" y="789" font-size="12" fill="#4E4740">stale warnings. Stale demotes, never deletes. Then ARM / FIX / AVOID.</text>
+<text x="120" y="800" font-size="11.5" font-family="ui-monospace,SFMono-Regular,Menlo,Consolas,monospace" fill="#1E1B18" font-weight="500">gates -&gt; defects+rules</text>
+<text x="938" y="800" font-size="11.5" font-family="ui-monospace,SFMono-Regular,Menlo,Consolas,monospace" fill="#7C736A" text-anchor="end">-&gt; retractions -&gt; tombstones</text>
+<rect x="28" y="826" width="924" height="90" fill="#FFFFFF" stroke="#DCD6CE"/>
+<rect x="28" y="826" width="74" height="90" fill="#EBE7E1" stroke="#DCD6CE"/>
+<text x="65" y="864" font-size="26" font-weight="700" fill="#B4531F" font-family="ui-monospace,SFMono-Regular,Menlo,Consolas,monospace" text-anchor="middle">7</text>
+<text x="65" y="882" font-size="9" fill="#7C736A" font-family="ui-monospace,SFMono-Regular,Menlo,Consolas,monospace" text-anchor="middle" letter-spacing="1">RENDER</text>
+<text x="120" y="851" font-size="15" font-weight="600" fill="#1E1B18">Three surfaces, one pipeline</text>
+<text x="120" y="870" font-size="12" fill="#4E4740">agent | actions | json. A zero-match result carries the store size, so 'no rules apply' can</text>
+<text x="120" y="885" font-size="12" fill="#4E4740">never be confused with 'the store is empty'.</text>
+<text x="120" y="896" font-size="11.5" font-family="ui-monospace,SFMono-Regular,Menlo,Consolas,monospace" fill="#1E1B18" font-weight="500">hook | MCP | CI</text>
+<text x="28" y="968" font-size="11" font-family="ui-monospace,SFMono-Regular,Menlo,Consolas,monospace" fill="#7C736A">src/okl/core.py check() / _in_scope() . src/okl/store.py search() . regenerate: python3 docs/render_pipeline_diagram.py</text>
+</svg>

org_knowledge_layer-0.5.0/docs/posts/04-the-elegant-change-was-the-wrong-one.md

@@ -0,0 +1,55 @@
+# The elegant change was the wrong one
+
+*Part 4 of 3: The loop that learns. What happened when the method was pointed at the tool that implements it.*
+
+I built a thing that tells you to verify your claims mechanically, then spent a day running it against itself. It found nineteen defects. This is about what they had in common, and about the one that survived every check I had.
+
+## Everything that broke had never been run
+
+The MCP server could not start. The library it depends on had renamed the class it imports, so `pip install` produced a server that failed on load, and the error handler told you to install the extra you had just installed.
+
+The Postgres path had never touched Postgres. The schema was right, the queries were right, and the parity test I wrote to prove it opened with `DELETE FROM node` against whatever database you pointed it at. Anyone running it against their real store to check parity would have lost everything in it.
+
+The shared service, deployed, answered 500 to every request. The ASGI entrypoint documented in its own docstring resolved to a module-level `None`. The process started, bound its port, and passed a liveness check that only asked whether something was listening.
+
+And the token that gated writes did not gate reads, so `GET /nodes` handed the entire store to anyone who found the URL. For a knowledge layer that is not a minor leak. The store is a catalogue of the places an organisation already knows it is weak.
+
+Four failures, one shape. Each lived in a surface nobody had ever exercised. Not badly written, not under-reviewed. Unrun. The defects clustered exactly where you would predict if you were being honest with yourself, which is the least surprising distribution in software and somehow always a surprise.
+
+## The one that was carefully reasoned
+
+Late in the day I found a real problem. Briefings in a Python repository were full of .NET rules. The vocabulary already separates *stacks* from *subjects*, so the fix looked obvious: a record naming a stack should only reach a repository that declared that stack, while subject tags stay permissive. One universal subject was rescuing every off-stack record into every project.
+
+I implemented it. It passed its tests. It passed the architecture review. The reasoning was drawn from the system's own documented distinction, and I wrote three paragraphs of commentary explaining why it was correct.
+
+Then the A/B measured it, and the briefed arm posted its worst result across four runs.
+
+The cause took ten minutes to find and was not subtle once seen. One rule reads *"in-memory rate limiters silently weaken to N times the limit at N instances."* It is tagged `dotnet`. It is also true of every runtime ever written. The tag records where the lesson was **found**, not where it **applies**, because tags get assigned in bulk when a corpus is imported from a codebase. My filter read provenance as applicability and hid 35 of the 172 records in the store at the time, including an IDOR rule, a data-transposition defect, and the rate-limiter rule itself. The generated code then reproduced the exact defect the hidden rule described, on a task where the unaided arm reproduced nothing.
+
+Most of the records tagged `dotnet` in that store are portable engineering lessons. I will not put a percentage on it, because the only way I have to classify them is keyword matching on their titles, and the answer moves by twenty points depending on which words I pick. That is the sort of number this series is about not quoting. The unambiguous cases are enough: an IDOR rule, JWT clock skew, fanout exchanges discarding unroutable messages, time-ordered primary keys. None of those is about .NET, and no amount of reading the filter's code would have told me, because the code was doing precisely what I designed it to do.
+
+## Reasoning is not evidence, and review is not measurement
+
+That change had everything except a measurement. It had a rationale, a test suite, a passing review, and a comment block. What it did not have was a number, and the number was the only thing that disagreed with it.
+
+The uncomfortable part is the ranking. Of the nineteen defects, the four unrun surfaces were the easiest to find, because running them was enough. The carefully argued one needed a controlled experiment to catch, and I would have shipped it as an improvement.
+
+There is a corollary I like less. Reverting was correct, but doing it in that order was not. The change should never have run without a written prediction and, more usefully, a list of which cases could plausibly lose a record they depend on. That list would have named the failing task before the experiment started, for free.
+
+## The cheapest check was the one nobody was running
+
+Whether a record reaches a briefing is deterministic. It needs no model, no samples, and no judge. It is a query.
+
+Two separate regressions were each discovered only after a full run: twenty-five minutes and forty-eight model calls, to learn something a database could have answered instantly. So now a pre-flight asks it directly before anything is spent: for each case, is the rule it exists to test actually present in the retrieval it will receive?
+
+The first time it ran, it found that two of eight cases had not been receiving their rule at all. One was filtered out by a tag the host repository never declared. The other had been silently dropped by a relevance cutoff added weeks earlier, in a change whose own report concluded it caused no retrieval miss. That conclusion had been drawn from outcomes rather than from asking the question. The case still looked healthy, because something else in the briefing happened to prevent the defect. It was never evidence for the rule it was filed under.
+
+That correction is in the report now, above the section it corrects.
+
+## What I would take from this
+
+Untested surfaces contain defects in proportion to how untested they are, and that is boring and cheap to fix: run them. The expensive lesson is the second one.
+
+The changes most likely to be wrong are the ones you can argue for best. A change with a clean rationale, a green suite, and an approving reviewer has passed every filter except contact with reality, and the more elegant the argument, the more of your judgment it has already borrowed. So decide in advance what would falsify it, write that down where you cannot revise it later, and make sure the cheap deterministic check runs before the expensive stochastic one.
+
+None of that is a new idea. What was new to me was watching it fail on the tool built to enforce it, in a session where I was actively looking.