org-knowledge-layer 0.1.2__tar.gz → 0.2.0__tar.gz

{org_knowledge_layer-0.1.2 → org_knowledge_layer-0.2.0}/.claude/settings.local.json

@@ -90,13 +90,54 @@
       "Bash(git -c core.hooksPath=/dev/null commit -qm 'Post 1: concede the crowded category, name the narrow differentiator *)",
       "Bash(git -c core.hooksPath=/dev/null commit -qm 'Public-repo hygiene: SECURITY.md, CONTRIBUTING.md, templates, provenance wording *)",
       "Bash(grep -n \"^  [a-z-]*:$\\\\|^name:\\\\|runs-on\" .github/workflows/ci.yml)",
-      "Bash(git -C /Users/joshuadell/Dev/okl push --dry-run origin main)"
+      "Bash(git -C /Users/joshuadell/Dev/okl push --dry-run origin main)",
+      "Bash(git -c core.hooksPath=/dev/null commit -qm 'v0.1.2: ship the provenance fix and the security warning *)",
+      "Bash(rm -rf v12test)",
+      "Bash(python3 -m venv v12test)",
+      "Bash(./v12test/bin/pip install *)",
+      "Bash(./v12test/bin/okl --help)",
+      "Bash(./v12test/bin/python -c ' *)",
+      "Bash(ruff check *)",
+      "Bash(curl -s \"https://pypi.org/pypi/org-knowledge-layer/0.1.3/json\")",
+      "Bash(/tmp/v13/bin/pip show *)",
+      "Bash(xargs -I{} gh run view {} --log-failed)",
+      "Bash(grep -vE \"^$\")",
+      "Bash(git -c core.hooksPath=/dev/null commit -qm 'Fix the CI break the PyPI rename caused: detect by source, not by name *)",
+      "Bash(git -c core.hooksPath=/dev/null commit -qm 'README: say what okl is, and exactly what it keeps from drifting *)",
+      "Bash(sed 's|cd \"$\\(dirname \"$0\"\\)/\\\\.\\\\.\"|cd \"$\\(pwd\\)\"|' src/okl/scaffold/gates/check-links.sh)",
+      "Bash(bash /tmp/links.sh)",
+      "Bash(sed 's|cd \"$\\(dirname \"$0\"\\)/\\\\.\\\\.\"|cd \"$\\(pwd\\)\"|' src/okl/scaffold/gates/check-diagram-pairs.sh)",
+      "Bash(bash /tmp/dia.sh)",
+      "Bash(git -C /Users/joshuadell/NovaCraft log --oneline --diff-filter=A -- \".claude/skills/excalidraw-diagram/SKILL.md\")",
+      "Bash(git -C /Users/joshuadell/NovaCraft log --format=\"%h %ad %s\" --date=short --diff-filter=A -- \".claude/skills/excalidraw-diagram/\")",
+      "Bash(git -C /Users/joshuadell/NovaCraft log --oneline -- \".claude/skills/excalidraw-diagram/\")",
+      "Bash(git -c core.hooksPath=/dev/null commit -qm 'Be accurate about which agents get enforcement, and about what init writes *)",
+      "Bash(tee /tmp/briefing.txt)",
+      "Bash(awk '{printf \"payload: %s bytes, ~%d tokens\\\\n\",$1,$1/4}')",
+      "Bash(/tmp/v13/bin/okl check *)",
+      "Bash(/tmp/v13/bin/okl seed *)",
+      "Bash(python3 -m okl seed)",
+      "Bash(/Users/joshuadell/Dev/okl/.venv/bin/okl seed *)",
+      "Bash(python3 -m okl init --repo myproject --interests \"security,python-rag\")",
+      "Bash(echo \"=== exit=$? \\(nothing imported\\) ===\")",
+      "Bash(python3 -m okl seed /Users/joshuadell/Dev/okl/seed/rag-defects.json)",
+      "Bash(python3 -m okl seed /Users/joshuadell/Dev/okl/seed/dotnet-defects.json)",
+      "Bash(sqlite3 .okl/okl.db \"select count\\(*\\) from node;\")",
+      "Bash(python3 -m okl check --task \"add an endpoint that returns an order for the logged-in user\")",
+      "Bash(awk '{printf \"briefing now: %s bytes \\(~%d tokens\\), was ~4381\\\\n\",$1,$1/4}')",
+      "Bash(python3 -m okl bootstrap --repo myproject)",
+      "Bash(seed)",
+      "Bash(check)",
+      "Bash(okl bootstrap *)",
+      "Bash(git -c core.hooksPath=/dev/null commit -qm 'First-run experience: seeding is a choice, briefings are capped, empty states are honest *)",
+      "Bash(git -c core.hooksPath=/dev/null commit -q --amend -F /tmp/msg.txt)"
     ],
     "additionalDirectories": [
       "/Users/joshuadell/Dev/okl/e2e/scratch-briefed/.okl",
       "/Users/joshuadell/Dev/emeraldleaf-dev/src/pages",
       "/Users/joshuadell/Dev/emeraldleaf-dev/src/assets",
-      "/Users/joshuadell/Dev/emeraldleaf-dev/src"
+      "/Users/joshuadell/Dev/emeraldleaf-dev/src",
+      "/Users/joshuadell/NovaCraft/.claude/skills/excalidraw-diagram"
     ]
   }
 }

{org_knowledge_layer-0.1.2/src/okl/scaffold/ci → org_knowledge_layer-0.2.0/.github/workflows}/okl-verify.yml

@@ -27,13 +27,13 @@ jobs:
         with:
           python-version: "3.13"
       - name: Install okl
-        # Consumer repos install the released package; in okl's own repo this
-        # workflow dogfoods the working tree (pip install okl would 404 — not on PyPI yet).
+        # Detect by the package source, not the distribution name: the name changed once
+        # (PyPI rejects "okl" as confusable) and a name-based check silently broke with it.
         run: |
-          if grep -q '^name = "okl"' pyproject.toml 2>/dev/null; then
+          if [ -f src/okl/cli.py ]; then
             pip install -e .
           else
-            pip install okl
+            pip install org-knowledge-layer
           fi
 
       - name: Connect to the shared layer (optional — skipped when secrets are unset)

{org_knowledge_layer-0.1.2 → org_knowledge_layer-0.2.0}/CONTRIBUTING.md

@@ -49,6 +49,17 @@ it is the actual contract. The parts that will fail your build if you miss them:
   cutoff that is still unfinished.
 - **Portability fixes.** Hooks, path resolution, and CI have been exercised on macOS and
   GitHub Actions and nowhere else.
+- **Hook wiring for another agent.** `okl init` auto-registers hooks for Claude Code
+  only, so everywhere else the pre-task read is discretionary rather than enforced. The
+  scripts in `src/okl/scaffold/hooks/` are plain bash reading JSON on stdin and writing
+  the briefing to stdout; nothing in them is Claude-specific. What is missing is the
+  per-agent registration, plus confirming the agent fires an event before the model reads
+  the prompt (Codex CLI documents `userpromptsubmit`; OpenCode's plugin API appears to
+  cover tool events but not pre-prompt, so there it may only ever be a tool call). A PR adding `okl init --agent <name>` for the tool you actually use
+  daily would be the single most valuable contribution here. Bring evidence it fires: a
+  behavioral check against a bare control repo, not just a log line, because a hook that
+  fires is not a hook that is heard.
+
 - **A live-Postgres test.** The ranked search path for Postgres is currently asserted at
   the SQL-shape level against a fake connection; it has never run against a real server.
 

{org_knowledge_layer-0.1.2 → org_knowledge_layer-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: org-knowledge-layer
-Version: 0.1.2
+Version: 0.2.0
 Summary: Org Knowledge Layer — an installable sixth surface that carries encoded engineering lessons across repos.
 Author: Joshua Dell
 License: MIT
@@ -67,6 +67,58 @@ stdlib-only with zero required dependencies.
 
 ---
 
+## What okl is
+
+**A store of your engineering rules, and the machinery that keeps them true.**
+
+Two things ship in the package. They are not coequal:
+
+- **The knowledge layer** is the product. Typed records (rules, architecture decisions,
+  known defects, gates, tombstones, retractions) that live outside any one repo, get
+  retrieved into an agent's context before a task, and go stale loudly when the code
+  they describe moves on. Everything measured in [evals/REPORT.md](evals/REPORT.md)
+  measures this.
+- **`okl scaffold`** is a starter kit for the in-repo discipline the store assumes: a
+  lean canon file, mechanical gates, registries, a review agent, and an eval harness.
+  It is useful on its own and it has never been measured. Use it to get a new repo to
+  the state where a shared store has something to attach to.
+
+| Piece | What it is | Where it lives |
+|---|---|---|
+| **client** (`okl` CLI + agent tools) | `check` / `record` / `verify` / `drift` / `search` / `seed` | installed per-repo (this package) |
+| **shared layer** (`okl serve`) | one small service owning the database, so many repos share one store | one place you run it |
+| **scaffold** (`okl scaffold`) | the in-repo starter files: canon, gates, registries, evals | stamped into each repo, optional |
+
+## What it keeps from drifting, and how
+
+Knowledge rots in a specific way: the code changes and everything written *about* the
+code silently stops being true. Five mechanisms catch five different versions of that,
+and it is worth knowing which one catches what, because they do not overlap.
+
+| Drift | Caught by | How it works | Fires when |
+|---|---|---|---|
+| **A rule vs. the code it governs** | `okl drift --gate` | a record declares the path globs it governs; git is asked for the last commit touching them | that commit is newer than the record's last verification |
+| **A retired identifier reappearing in prose** | `check-tombstones.sh` | greps tracked source, docs, comments and config for every tombstoned name | any non-allowlisted hit |
+| **A withdrawn claim being restated** | `check-retractions.sh` | greps tracked docs for the exact quoted claim from the retraction registry | the quote appears outside the registry |
+| **A doc nobody links to** | `check-doc-orphans.sh` | reachability check from hub files through `docs/` | a doc is unreachable, so it drifts unread |
+| **A link pointing at a file that moved** | `check-links.sh` | resolves every local markdown link against `git ls-files` | the target does not exist |
+| **A diagram source with no rendered image** | `check-diagram-pairs.sh` | pairs each editable source with its export; format-agnostic via `OKL_DIAGRAM_SRC_EXT`/`OUT_EXT` | reviewers would see nothing. A hand-authored image with no source is noted, never failed, and a repo with no diagram sources is a clean no-op |
+| **Verification going quietly stale** | TTL + `verified_by` | records carry when they were last verified and by which observed check | past its TTL, a record is shown demoted rather than deleted |
+
+Two honest limits on that table:
+
+- **Diagram *content* is still a human job.** `check-diagram-pairs.sh` proves the rendered
+  image exists; nothing proves it matches the source it was exported from, or that either
+  matches the code. For that, name the diagram in a record's `--files` alongside the code
+  it depicts, so changing the code turns the drift gate red until someone re-verifies the
+  picture. This repo does exactly that with its own architecture diagram and README.
+- **Comments are covered only by the identifier and claim gates.** A stale comment that
+  names no tombstoned identifier and restates no retracted claim will not be caught.
+- **`okl drift` only watches what a record claims.** A file no record governs is not
+  watched by anything. Coverage is a curation decision, and the gap is invisible until
+  something breaks — which is why the mechanical gates above scan *everything tracked*
+  rather than only what is enrolled.
+
 ## Where this sits (2026): a crowded space, entered anyway
 
 **This is not a novel idea, and you should know that before reading further.** Agent
@@ -246,6 +298,29 @@ okl init --repo my-repo        # writes .okl/config.json; installs the pre-task
 okl connect https://okl.myorg.dev   # optional: point at the shared service (else local file)
 ```
 
+### What `okl init` writes to your repo
+
+Run `okl init --dry-run` first: it lists every path and writes nothing. In full, `init`
+touches only the current directory, and only these:
+
+| Path | What it is |
+|---|---|
+| `.okl/config.json` | repo name, subject interests, and the path to your `okl` binary |
+| `.claude/hooks/userpromptsubmit-okl-check.sh` | **executable**; runs when you submit a task, injects the briefing |
+| `.claude/hooks/stop-okl-encode.sh` | **executable**; runs at session end, asks what was learned |
+| `.claude/settings.json` | registers those two hooks (merged in place; your existing keys are preserved) |
+| `.mcp.json` | registers the okl MCP server — only when the `mcp` extra is installed |
+| `.github/workflows/okl-verify.yml` | **a CI workflow** running the drift gate on pull requests |
+
+Two of those deserve a second look before you run it: the hooks are shell scripts that
+execute automatically during agent sessions (the check hook can *block* a task when the
+store is unreachable — that is the fail-closed design), and the CI workflow will run in
+your Actions. Both are plain text you can read first, in
+[`src/okl/scaffold/hooks/`](src/okl/scaffold/hooks/) and
+[`src/okl/scaffold/ci/`](src/okl/scaffold/ci/). Nothing executes at install time; nothing
+is written outside the directory you run `init` in; nothing contacts a network unless you
+run `okl connect` and point it somewhere yourself.
+
 `init` writes `.okl/config.json`. If the repo uses a coding agent with a `.claude/`
 directory, it also installs two hooks: a `UserPromptSubmit` hook that runs `check` on
 the prompt you actually typed and puts the briefing into the model's context (the
@@ -261,6 +336,18 @@ reading the AGENTS.md convention gets the same rules Claude Code does (byte-iden
 test-enforced). The hooks themselves are Claude Code-specific; other agents get the
 canon via AGENTS.md and the store via the MCP server (`okl mcp`).
 
+That split matters: on Claude Code the pre-task read is *enforced* (fail-closed hook);
+everywhere else it is *available* (a tool call or a shell command), which is
+discretionary — the thing enforcement exists to avoid. The hook scripts themselves are
+plain bash reading JSON on stdin, so nothing in them is Claude-specific; what is missing
+for other agents is the config that registers them, and whether the agent fires an event
+early enough to matter. Codex CLI documents a `userpromptsubmit` hook, which is the right
+shape; Copilot, Gemini CLI and Cursor have hook systems worth checking against your
+version; OpenCode's plugin API captures tool events but, as of this writing, no
+pre-prompt event — so there the read stays a tool call rather than a gate. Verify against
+your agent's current docs before trusting any of that. Wiring one up is a well-shaped
+contribution — see [CONTRIBUTING.md](CONTRIBUTING.md).
+
 Hooks run in whatever environment the agent harness spawns — often without your venv or
 pipx bin dir on PATH — so both hooks resolve the `okl` binary in layers: the `OKL_BIN`
 env var, then the `okl_bin` path `init` pins into `.okl/config.json` (machine-local),
@@ -275,6 +362,7 @@ mode, good for trying it before you deploy anything.
 ```bash
 # 1. READ the relevant lessons before starting a task (the load-bearing move)
 okl check --task "add an endpoint that returns an order for the logged-in user"
+#   add --format actions --limit 3 for a ~240-token version (subagents, CI)
 
 # 2. RECORD a lesson after you learn it, with an actionable symptom/cause/fix
 okl record --type Defect --scope org --tags "security" \
@@ -313,6 +401,59 @@ okl metric           # recurrence-after-arming: defect classes that came back in
                      #   where a catching check existed but wasn't turned on
 ```
 
+## Subagents and small context budgets
+
+A full briefing costs roughly **4,400 tokens** — fine for a main session with a large
+window, punishing for a subagent working in a few thousand. That asymmetry matters
+because subagents are exactly where org rules get lost: a focused worker handling one
+subtask has the least context and the most need for "here is the mistake this codebase
+already made."
+
+`--format actions` solves it by dropping everything except the imperative list:
+
+```bash
+okl check --task "add an endpoint returning an order for the logged-in user" \
+  --format actions --limit 3
+```
+
+```
+OKL — 3 rule(s) apply before you start:
+- FIX: Missing ownership scope check is an IDOR (CWE-639) [when: an endpoint fetches an
+  entity by id with no owner/tenant predicate]
+  -> add the caller's owner id to the WHERE clause; return 404 (not 403) on no match
+...
+```
+
+**Measured on this repo's own store:** ~240 tokens at `--limit 3`, ~390 at `--limit 5`,
+~630 at `--limit 8`, against ~2,650 for the full briefing. Cheap enough to call per subtask.
+
+The full briefing is itself capped: `check` keeps the top `--limit` records (12 by
+default) from the ranked, filtered set and says how many it trimmed. Before that cutoff
+existed, one task on this store returned 20 records and ~4,400 tokens. Re-running the A/B
+after adding it showed no retrieval miss — the one task that regressed still had its rule
+in the briefing and the model simply did not follow it, which is a compliance problem
+rather than a retrieval one. See [evals/REPORT.md](evals/REPORT.md).
+
+What it drops: the bucketed sections, the prose bodies explaining *why* each record
+exists, prior-art notes, and the stale-record footer. What it keeps is what changes
+behaviour: the verb, the symptom to watch for, and the fix.
+
+**Wiring it into a subagent.** Three ways, in order of how much enforcement you get:
+
+1. **The MCP tool** — `okl_check(task=..., compact=True, limit=3)`. Any subagent with
+   MCP access can call it. Discretionary: the agent has to choose to.
+2. **In the subagent's prompt** — have the spawning agent run `okl check --format
+   actions --limit 3` and paste the result into the subtask description. Not
+   discretionary, and it costs the parent almost nothing.
+3. **A wrapper script** that runs the check and prepends it to whatever prompt it is
+   handed. This is the enforced version for orchestration you control.
+
+**A caveat worth stating.** `--limit` caps how many records the briefing draws on, and
+ranking decides which survive. If a task's most relevant rule ranks fourth and you ask
+for three, you will not see it, and nothing will tell you. The full briefing exists
+because it does not make that trade. Use the compact form where a token budget forces
+the choice, not by default.
+
 ## Verification: don't let a step grade itself
 
 A step reporting "I succeeded" and the work actually being done are two different facts,
@@ -348,17 +489,36 @@ folder.) Two clarifications that stop the common misreadings:
 
 ## Seed it (so the very first `check` returns something)
 
-An empty store returns nothing. You can hand-`record` your first lessons, or load a
-starter file — a JSON list of notes and links:
+An empty store returns nothing, and says so — a check against an empty store reports
+that it proved nothing rather than reporting "no rules apply". Three ways to fill it:
+
+**1. See what ships, then choose.** A bare `okl seed` imports nothing; it lists the
+bundled packs with their record counts and subject tags, marking the ones that match
+this repo's declared interests:
 
 ```bash
-okl seed seed/react-defects.json      # or point at a directory to load several
+okl seed                              # list the packs, import nothing
+okl seed <path>/rag-defects.json      # import one
+okl seed --all                        # import every pack (explicit on purpose)
 ```
 
-The bundled seed files hold real, dated lessons from a few production codebases
-(a .NET service, a geospatial ML pipeline, a Python search service, a React app).
-Treat them as examples of the format and as genuinely useful starting defects; delete
-what doesn't apply to you.
+The packs hold real, dated records from production codebases (a .NET service, a
+geospatial ML pipeline, a Python RAG service, a React app). They are org-scoped, so
+importing packs for stacks you do not use fills every briefing here with noise about
+frameworks you will never touch — which is why `--all` is opt-in rather than default.
+
+**2. Generate records from this codebase.** If you use a coding agent, the scaffold
+stamps a `/seed-from-codebase` command that has the agent read your repo — the guard
+rails already in the code, what CI enforces, the fix commits, the existing canon — and
+propose records with a `file:line` citation each. Everything it proposes is repo-scoped
+and unverified by design; it writes a reviewable file and imports nothing, because a
+plausible rule no file supports is worse than an empty store.
+
+**3. `okl bootstrap`** greps git history and file names for candidates. It is the weakest
+of the three and comes up empty on young repos; prefer option 2 when an agent is available.
+
+Whichever you use, review before importing. Choosing a record's scope is the curation
+step that keeps a shared layer from filling with one project's noise.
 
 ---
 
@@ -389,14 +549,8 @@ TDD, plan writing/execution, git-worktree isolation) are **not bundled** — the
 best maintained in third-party collections, so `skills/RECOMMENDED-COMPANIONS.md`
 points at those instead of vendoring someone else's work and its cross-references.
 
-The scaffold is independent of the knowledge store — use either half on its own.
-
-## The two halves
-
-| Piece | What it is | Where it lives |
-|---|---|---|
-| **client** (`okl` CLI + agent tools) | `check` / `record` / `search` / `link` / `drift` / `seed` / … | installed per-repo (this package) |
-| **shared layer** (`okl serve`) | a small web service that owns the database, so many repos share one store | one place you run it |
+The scaffold runs with no store at all; the store works in a repo that never scaffolded.
+They are complementary, not a package deal.
 
 **Storage is swappable** via one environment variable — your commands never change:
 

{org_knowledge_layer-0.1.2 → org_knowledge_layer-0.2.0}/README.md

@@ -35,6 +35,58 @@ stdlib-only with zero required dependencies.
 
 ---
 
+## What okl is
+
+**A store of your engineering rules, and the machinery that keeps them true.**
+
+Two things ship in the package. They are not coequal:
+
+- **The knowledge layer** is the product. Typed records (rules, architecture decisions,
+  known defects, gates, tombstones, retractions) that live outside any one repo, get
+  retrieved into an agent's context before a task, and go stale loudly when the code
+  they describe moves on. Everything measured in [evals/REPORT.md](evals/REPORT.md)
+  measures this.
+- **`okl scaffold`** is a starter kit for the in-repo discipline the store assumes: a
+  lean canon file, mechanical gates, registries, a review agent, and an eval harness.
+  It is useful on its own and it has never been measured. Use it to get a new repo to
+  the state where a shared store has something to attach to.
+
+| Piece | What it is | Where it lives |
+|---|---|---|
+| **client** (`okl` CLI + agent tools) | `check` / `record` / `verify` / `drift` / `search` / `seed` | installed per-repo (this package) |
+| **shared layer** (`okl serve`) | one small service owning the database, so many repos share one store | one place you run it |
+| **scaffold** (`okl scaffold`) | the in-repo starter files: canon, gates, registries, evals | stamped into each repo, optional |
+
+## What it keeps from drifting, and how
+
+Knowledge rots in a specific way: the code changes and everything written *about* the
+code silently stops being true. Five mechanisms catch five different versions of that,
+and it is worth knowing which one catches what, because they do not overlap.
+
+| Drift | Caught by | How it works | Fires when |
+|---|---|---|---|
+| **A rule vs. the code it governs** | `okl drift --gate` | a record declares the path globs it governs; git is asked for the last commit touching them | that commit is newer than the record's last verification |
+| **A retired identifier reappearing in prose** | `check-tombstones.sh` | greps tracked source, docs, comments and config for every tombstoned name | any non-allowlisted hit |
+| **A withdrawn claim being restated** | `check-retractions.sh` | greps tracked docs for the exact quoted claim from the retraction registry | the quote appears outside the registry |
+| **A doc nobody links to** | `check-doc-orphans.sh` | reachability check from hub files through `docs/` | a doc is unreachable, so it drifts unread |
+| **A link pointing at a file that moved** | `check-links.sh` | resolves every local markdown link against `git ls-files` | the target does not exist |
+| **A diagram source with no rendered image** | `check-diagram-pairs.sh` | pairs each editable source with its export; format-agnostic via `OKL_DIAGRAM_SRC_EXT`/`OUT_EXT` | reviewers would see nothing. A hand-authored image with no source is noted, never failed, and a repo with no diagram sources is a clean no-op |
+| **Verification going quietly stale** | TTL + `verified_by` | records carry when they were last verified and by which observed check | past its TTL, a record is shown demoted rather than deleted |
+
+Two honest limits on that table:
+
+- **Diagram *content* is still a human job.** `check-diagram-pairs.sh` proves the rendered
+  image exists; nothing proves it matches the source it was exported from, or that either
+  matches the code. For that, name the diagram in a record's `--files` alongside the code
+  it depicts, so changing the code turns the drift gate red until someone re-verifies the
+  picture. This repo does exactly that with its own architecture diagram and README.
+- **Comments are covered only by the identifier and claim gates.** A stale comment that
+  names no tombstoned identifier and restates no retracted claim will not be caught.
+- **`okl drift` only watches what a record claims.** A file no record governs is not
+  watched by anything. Coverage is a curation decision, and the gap is invisible until
+  something breaks — which is why the mechanical gates above scan *everything tracked*
+  rather than only what is enrolled.
+
 ## Where this sits (2026): a crowded space, entered anyway
 
 **This is not a novel idea, and you should know that before reading further.** Agent
@@ -214,6 +266,29 @@ okl init --repo my-repo        # writes .okl/config.json; installs the pre-task
 okl connect https://okl.myorg.dev   # optional: point at the shared service (else local file)
 ```
 
+### What `okl init` writes to your repo
+
+Run `okl init --dry-run` first: it lists every path and writes nothing. In full, `init`
+touches only the current directory, and only these:
+
+| Path | What it is |
+|---|---|
+| `.okl/config.json` | repo name, subject interests, and the path to your `okl` binary |
+| `.claude/hooks/userpromptsubmit-okl-check.sh` | **executable**; runs when you submit a task, injects the briefing |
+| `.claude/hooks/stop-okl-encode.sh` | **executable**; runs at session end, asks what was learned |
+| `.claude/settings.json` | registers those two hooks (merged in place; your existing keys are preserved) |
+| `.mcp.json` | registers the okl MCP server — only when the `mcp` extra is installed |
+| `.github/workflows/okl-verify.yml` | **a CI workflow** running the drift gate on pull requests |
+
+Two of those deserve a second look before you run it: the hooks are shell scripts that
+execute automatically during agent sessions (the check hook can *block* a task when the
+store is unreachable — that is the fail-closed design), and the CI workflow will run in
+your Actions. Both are plain text you can read first, in
+[`src/okl/scaffold/hooks/`](src/okl/scaffold/hooks/) and
+[`src/okl/scaffold/ci/`](src/okl/scaffold/ci/). Nothing executes at install time; nothing
+is written outside the directory you run `init` in; nothing contacts a network unless you
+run `okl connect` and point it somewhere yourself.
+
 `init` writes `.okl/config.json`. If the repo uses a coding agent with a `.claude/`
 directory, it also installs two hooks: a `UserPromptSubmit` hook that runs `check` on
 the prompt you actually typed and puts the briefing into the model's context (the
@@ -229,6 +304,18 @@ reading the AGENTS.md convention gets the same rules Claude Code does (byte-iden
 test-enforced). The hooks themselves are Claude Code-specific; other agents get the
 canon via AGENTS.md and the store via the MCP server (`okl mcp`).
 
+That split matters: on Claude Code the pre-task read is *enforced* (fail-closed hook);
+everywhere else it is *available* (a tool call or a shell command), which is
+discretionary — the thing enforcement exists to avoid. The hook scripts themselves are
+plain bash reading JSON on stdin, so nothing in them is Claude-specific; what is missing
+for other agents is the config that registers them, and whether the agent fires an event
+early enough to matter. Codex CLI documents a `userpromptsubmit` hook, which is the right
+shape; Copilot, Gemini CLI and Cursor have hook systems worth checking against your
+version; OpenCode's plugin API captures tool events but, as of this writing, no
+pre-prompt event — so there the read stays a tool call rather than a gate. Verify against
+your agent's current docs before trusting any of that. Wiring one up is a well-shaped
+contribution — see [CONTRIBUTING.md](CONTRIBUTING.md).
+
 Hooks run in whatever environment the agent harness spawns — often without your venv or
 pipx bin dir on PATH — so both hooks resolve the `okl` binary in layers: the `OKL_BIN`
 env var, then the `okl_bin` path `init` pins into `.okl/config.json` (machine-local),
@@ -243,6 +330,7 @@ mode, good for trying it before you deploy anything.
 ```bash
 # 1. READ the relevant lessons before starting a task (the load-bearing move)
 okl check --task "add an endpoint that returns an order for the logged-in user"
+#   add --format actions --limit 3 for a ~240-token version (subagents, CI)
 
 # 2. RECORD a lesson after you learn it, with an actionable symptom/cause/fix
 okl record --type Defect --scope org --tags "security" \
@@ -281,6 +369,59 @@ okl metric           # recurrence-after-arming: defect classes that came back in
                      #   where a catching check existed but wasn't turned on
 ```
 
+## Subagents and small context budgets
+
+A full briefing costs roughly **4,400 tokens** — fine for a main session with a large
+window, punishing for a subagent working in a few thousand. That asymmetry matters
+because subagents are exactly where org rules get lost: a focused worker handling one
+subtask has the least context and the most need for "here is the mistake this codebase
+already made."
+
+`--format actions` solves it by dropping everything except the imperative list:
+
+```bash
+okl check --task "add an endpoint returning an order for the logged-in user" \
+  --format actions --limit 3
+```
+
+```
+OKL — 3 rule(s) apply before you start:
+- FIX: Missing ownership scope check is an IDOR (CWE-639) [when: an endpoint fetches an
+  entity by id with no owner/tenant predicate]
+  -> add the caller's owner id to the WHERE clause; return 404 (not 403) on no match
+...
+```
+
+**Measured on this repo's own store:** ~240 tokens at `--limit 3`, ~390 at `--limit 5`,
+~630 at `--limit 8`, against ~2,650 for the full briefing. Cheap enough to call per subtask.
+
+The full briefing is itself capped: `check` keeps the top `--limit` records (12 by
+default) from the ranked, filtered set and says how many it trimmed. Before that cutoff
+existed, one task on this store returned 20 records and ~4,400 tokens. Re-running the A/B
+after adding it showed no retrieval miss — the one task that regressed still had its rule
+in the briefing and the model simply did not follow it, which is a compliance problem
+rather than a retrieval one. See [evals/REPORT.md](evals/REPORT.md).
+
+What it drops: the bucketed sections, the prose bodies explaining *why* each record
+exists, prior-art notes, and the stale-record footer. What it keeps is what changes
+behaviour: the verb, the symptom to watch for, and the fix.
+
+**Wiring it into a subagent.** Three ways, in order of how much enforcement you get:
+
+1. **The MCP tool** — `okl_check(task=..., compact=True, limit=3)`. Any subagent with
+   MCP access can call it. Discretionary: the agent has to choose to.
+2. **In the subagent's prompt** — have the spawning agent run `okl check --format
+   actions --limit 3` and paste the result into the subtask description. Not
+   discretionary, and it costs the parent almost nothing.
+3. **A wrapper script** that runs the check and prepends it to whatever prompt it is
+   handed. This is the enforced version for orchestration you control.
+
+**A caveat worth stating.** `--limit` caps how many records the briefing draws on, and
+ranking decides which survive. If a task's most relevant rule ranks fourth and you ask
+for three, you will not see it, and nothing will tell you. The full briefing exists
+because it does not make that trade. Use the compact form where a token budget forces
+the choice, not by default.
+
 ## Verification: don't let a step grade itself
 
 A step reporting "I succeeded" and the work actually being done are two different facts,
@@ -316,17 +457,36 @@ folder.) Two clarifications that stop the common misreadings:
 
 ## Seed it (so the very first `check` returns something)
 
-An empty store returns nothing. You can hand-`record` your first lessons, or load a
-starter file — a JSON list of notes and links:
+An empty store returns nothing, and says so — a check against an empty store reports
+that it proved nothing rather than reporting "no rules apply". Three ways to fill it:
+
+**1. See what ships, then choose.** A bare `okl seed` imports nothing; it lists the
+bundled packs with their record counts and subject tags, marking the ones that match
+this repo's declared interests:
 
 ```bash
-okl seed seed/react-defects.json      # or point at a directory to load several
+okl seed                              # list the packs, import nothing
+okl seed <path>/rag-defects.json      # import one
+okl seed --all                        # import every pack (explicit on purpose)
 ```
 
-The bundled seed files hold real, dated lessons from a few production codebases
-(a .NET service, a geospatial ML pipeline, a Python search service, a React app).
-Treat them as examples of the format and as genuinely useful starting defects; delete
-what doesn't apply to you.
+The packs hold real, dated records from production codebases (a .NET service, a
+geospatial ML pipeline, a Python RAG service, a React app). They are org-scoped, so
+importing packs for stacks you do not use fills every briefing here with noise about
+frameworks you will never touch — which is why `--all` is opt-in rather than default.
+
+**2. Generate records from this codebase.** If you use a coding agent, the scaffold
+stamps a `/seed-from-codebase` command that has the agent read your repo — the guard
+rails already in the code, what CI enforces, the fix commits, the existing canon — and
+propose records with a `file:line` citation each. Everything it proposes is repo-scoped
+and unverified by design; it writes a reviewable file and imports nothing, because a
+plausible rule no file supports is worse than an empty store.
+
+**3. `okl bootstrap`** greps git history and file names for candidates. It is the weakest
+of the three and comes up empty on young repos; prefer option 2 when an agent is available.
+
+Whichever you use, review before importing. Choosing a record's scope is the curation
+step that keeps a shared layer from filling with one project's noise.
 
 ---
 
@@ -357,14 +517,8 @@ TDD, plan writing/execution, git-worktree isolation) are **not bundled** — the
 best maintained in third-party collections, so `skills/RECOMMENDED-COMPANIONS.md`
 points at those instead of vendoring someone else's work and its cross-references.
 
-The scaffold is independent of the knowledge store — use either half on its own.
-
-## The two halves
-
-| Piece | What it is | Where it lives |
-|---|---|---|
-| **client** (`okl` CLI + agent tools) | `check` / `record` / `search` / `link` / `drift` / `seed` / … | installed per-repo (this package) |
-| **shared layer** (`okl serve`) | a small web service that owns the database, so many repos share one store | one place you run it |
+The scaffold runs with no store at all; the store works in a repo that never scaffolded.
+They are complementary, not a package deal.
 
 **Storage is swappable** via one environment variable — your commands never change:
 

{org_knowledge_layer-0.1.2/.github/workflows → org_knowledge_layer-0.2.0/ci}/okl-verify.yml

@@ -27,13 +27,13 @@ jobs:
         with:
           python-version: "3.13"
       - name: Install okl
-        # Consumer repos install the released package; in okl's own repo this
-        # workflow dogfoods the working tree (pip install okl would 404 — not on PyPI yet).
+        # Detect by the package source, not the distribution name: the name changed once
+        # (PyPI rejects "okl" as confusable) and a name-based check silently broke with it.
         run: |
-          if grep -q '^name = "okl"' pyproject.toml 2>/dev/null; then
+          if [ -f src/okl/cli.py ]; then
             pip install -e .
           else
-            pip install okl
+            pip install org-knowledge-layer
           fi
 
       - name: Connect to the shared layer (optional — skipped when secrets are unset)

{org_knowledge_layer-0.1.2 → org_knowledge_layer-0.2.0}/evals/REPORT.md

@@ -139,6 +139,36 @@ reproduced in 1/15.
 
 Conditional subset: 2/12 on the 4 tasks the baseline failed at least once.
 
+## 4b. Re-run after adding the relevance cutoff (2026-09-01)
+
+`check` gained a top-k cutoff: it keeps the highest-ranked `limit` records (12 by
+default) and reports how many it trimmed. That is a change to the retrieval path this
+report measures, so the A/B was re-run rather than assumed safe.
+
+| run | generator | judge | samples | baseline | briefed |
+|---|---|---|---|---|---|
+| ab-20260830-0003 (before cutoff) | sonnet | haiku | 3 | 8/24 (33%) | 1/24 (4%) |
+| **ab-20260901-0133 (after cutoff)** | sonnet | haiku | 3 | **10/24 (42%)** | **2/24 (8%)** |
+
+**Read the baseline first.** It moved 33% → 42% between runs, and the baseline arm never
+receives a briefing — nothing about it changed. That 9-point swing is run-to-run variance
+and sets the noise floor at n=24. The briefed arm's 4% → 8% is one additional
+reproduction, inside that band.
+
+**The one signal worth investigating** was `spa_tokens`, which went 0/3 → 2/3 briefed. If
+the cutoff had trimmed the relevant record, that would be the ADR's miss-rate trigger
+firing. It had not: the localStorage record appears in that task's briefing at
+`--limit 12` exactly as it does at `--limit 40`. The judge's verdicts show the model used
+`sessionStorage` via `WebStorageStateStore` and wrote a comment documenting the security
+trade-off — it had the rule, understood it, and chose a variant the strict signal still
+counts as web-storage persistence. (The earlier haiku run reproduced the same task 2/3
+before any cutoff existed.)
+
+That distinction is the one the flat-retrieval ADR is written around: its trigger is a
+**retrieval miss** — a record that exists in scope and was not surfaced — not a model
+failing to comply with a record it was handed. Measured miss rate after the cutoff
+remains zero. Compliance is a separate, unmeasured problem.
+
 ## 5. Findings
 
 1. **The briefing works, in both tiers.** Sonnet: 33% → 4%. Haiku: 38% → 12%. Every