org-knowledge-layer 0.3.1__tar.gz → 0.4.0__tar.gz

org_knowledge_layer-0.4.0/.github/dependabot.yml

@@ -0,0 +1,32 @@
+# Dependabot.
+#
+# This exists because of the SHA pinning, not despite it. Pinning actions to a commit
+# closes the "a mutable tag moved under me" hole and opens a quieter one: the pin never
+# updates, so a security fix in an action never arrives. Pinning without an update path
+# is how a repo ends up on a two-year-old checkout action and calls it hardening.
+# Dependabot rewrites the SHA and the trailing `# v5` comment together.
+version: 2
+
+updates:
+  - package-ecosystem: github-actions
+    directory: "/"
+    schedule:
+      interval: weekly
+    labels: ["dependencies", "ci"]
+    commit-message:
+      prefix: "ci"
+
+  - package-ecosystem: pip
+    directory: "/"
+    schedule:
+      interval: weekly
+    labels: ["dependencies"]
+    commit-message:
+      prefix: "deps"
+    # The gating tools are pinned exactly on purpose (a range lets a new release
+    # retro-fail a branch that changed nothing). Dependabot is the intended way to move
+    # those pins: a PR that runs the full suite against the new version before it lands,
+    # rather than a range that upgrades silently mid-branch.
+    groups:
+      dev-tooling:
+        patterns: ["pytest", "ruff", "mypy"]

org_knowledge_layer-0.4.0/.github/workflows/ci.yml

@@ -0,0 +1,88 @@
+# Repo CI — lints, type-checks and tests okl itself. (okl-verify.yml is different: it
+# demonstrates the product's own drift/method gates, the workflow consumers copy.)
+#
+# Hardened per the org rule this repo's own store carries ("CI workflow baseline:
+# pipefail, no persisted credentials, least-privilege permissions, concurrency groups —
+# pin actions"). It satisfied none of the five until this commit, which is the rule's own
+# symptom: an enforcement surface nothing triggers runs never.
+name: ci
+
+on:
+  push:
+    branches: [ "main" ]
+  pull_request:
+    branches: [ "main" ]
+
+# Least privilege: this job reads code and reports status. It never pushes.
+permissions:
+  contents: read
+
+# One run per ref. A superseded push should stop burning minutes on a result nobody
+# will read.
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+defaults:
+  run:
+    # Without pipefail a run block continues past a failed segment of a pipeline, so a
+    # green step can hide a red command.
+    shell: bash -euo pipefail {0}
+
+jobs:
+  lint-and-test:
+    runs-on: ubuntu-latest
+    steps:
+      # Actions pinned to a commit SHA, not a tag: a tag is mutable, so `@v5` is an
+      # unpinned dependency with write access to the runner.
+      - uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09  # v5
+        with:
+          # The diagram gate reads committed history (git show HEAD:...), not the
+          # checkout tree, so it needs more than the default shallow fetch.
+          fetch-depth: 0
+          # This job never pushes; leaving the token in .git/config lets any later step
+          # (or a compromised dependency) use it.
+          persist-credentials: false
+
+      - uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1  # v6
+        with:
+          python-version: "3.12"
+
+      - name: Install (dev extras)
+        run: pip install -e ".[dev]"
+
+      - name: Lint — ruff (config in pyproject.toml)
+        run: ruff check .
+
+      - name: Types — mypy
+        run: mypy src/okl
+
+      - name: Tests (with the coverage ratchet)
+        run: pytest -q --cov=okl
+
+      - name: Diagram figures trace to committed receipts
+        run: ./ci/check-diagram-figures.sh
+
+      # The content audits okl ships to consumers, run against okl itself. They were
+      # shipped for weeks without this repo running any of them — the "enforcement
+      # surface nothing triggers" failure, one level up: a gate whose author has never
+      # run it on their own tree.
+      - name: Method gates (links, doc orphans, diagram pairs, tombstones, canon size)
+        run: bash gates/run-gates.sh
+
+      # Secret scan over the FULL history, not the working tree. okl writes a bearer
+      # token into .okl/config.json, and the .gitignore it now drops there is the only
+      # thing between that and a commit — this is the check for when that fails.
+      #
+      # The upstream gitleaks-action is deliberately not used: it requires a paid licence
+      # key for organization-owned repositories, so it would break for anyone who forks
+      # this into an org. The binary has no such condition, and pinning the release keeps
+      # a new detection rule from retro-failing a branch that changed nothing.
+      - name: Secret scan — gitleaks
+        env:
+          GITLEAKS_VERSION: "8.30.1"
+        run: |
+          curl -sSfL -o /tmp/gitleaks.tar.gz \
+            "https://github.com/gitleaks/gitleaks/releases/download/v${GITLEAKS_VERSION}/gitleaks_${GITLEAKS_VERSION}_linux_x64.tar.gz"
+          tar -xzf /tmp/gitleaks.tar.gz -C /tmp gitleaks
+          /tmp/gitleaks git . --no-banner --redact --exit-code 1

org_knowledge_layer-0.4.0/.github/workflows/publish.yml

@@ -0,0 +1,90 @@
+# Release to PyPI on a version tag, using Trusted Publishing.
+#
+# There is no API token anywhere in this workflow, and none stored in the repository.
+# PyPI accepts the upload because GitHub vouches for it: the publish job mints a
+# short-lived OIDC token that names this repository, this workflow file and this
+# environment, and PyPI checks that against the trusted publisher it was told to expect.
+# A leaked repository secret cannot publish okl because there is no such secret.
+#
+# ONE-TIME SETUP ON PYPI (this workflow does nothing until it is done):
+#   pypi.org → the org-knowledge-layer project → Publishing → Add a pending publisher
+#     Owner:            emeraldleaf
+#     Repository:       okl
+#     Workflow name:    publish.yml
+#     Environment name: pypi
+# Then create the `pypi` environment under repo Settings → Environments. Adding a
+# required reviewer there makes every release a deliberate, approved act.
+name: publish
+
+on:
+  push:
+    tags: ["v*"]
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09  # v5
+        with:
+          persist-credentials: false
+
+      - uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1  # v6
+        with:
+          python-version: "3.12"
+
+      # The tag is the release's claim about what version this is; pyproject.toml is the
+      # version that actually gets uploaded. When they disagree, PyPI takes pyproject's
+      # answer and the tag becomes a lie that is permanent — you cannot reuse a version
+      # number on PyPI, so the mistake is not fixable, only worked around.
+      - name: Tag must match the version in pyproject.toml
+        run: |
+          tag="${GITHUB_REF_NAME#v}"
+          pkg="$(python -c "import tomllib,pathlib; print(tomllib.loads(pathlib.Path('pyproject.toml').read_text())['project']['version'])")"
+          echo "tag=$tag  pyproject=$pkg"
+          if [ "$tag" != "$pkg" ]; then
+            echo "::error::tag v$tag does not match pyproject version $pkg"
+            exit 1
+          fi
+
+      - name: Build
+        run: |
+          python -m pip install --upgrade build twine
+          python -m build
+          # `twine check` catches a malformed long_description, which PyPI rejects only
+          # after the upload has otherwise succeeded.
+          python -m twine check dist/*
+
+      - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02  # v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    # A named environment is what the PyPI trusted publisher is bound to, and it is where
+    # a required-reviewer rule can gate the release.
+    environment:
+      name: pypi
+      url: https://pypi.org/project/org-knowledge-layer/
+    permissions:
+      id-token: write      # mint the OIDC token PyPI verifies
+      attestations: write  # sign the artifacts
+      contents: read
+    steps:
+      - uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093  # v4
+        with:
+          name: dist
+          path: dist/
+
+      # Provenance: a signed statement that these exact files were built by this workflow
+      # from this commit. It is what lets someone verify the wheel on PyPI came from the
+      # source they are reading, rather than trusting that it did.
+      - uses: actions/attest-build-provenance@e8998f949152b193b063cb0ec769d69d929409be  # v2
+        with:
+          subject-path: "dist/*"
+
+      - uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33  # release/v1

{org_knowledge_layer-0.3.1 → org_knowledge_layer-0.4.0}/AGENTS.md

@@ -31,8 +31,9 @@ okl drift                          # rules whose governed source changed after v
 ## Rules that are enforced (and why)
 
 - **Mirror files are byte-identical, test-enforced**: `ci/okl-verify.yml` ==
-  `.github/workflows/okl-verify.yml` == `src/okl/scaffold/ci/okl-verify.yml`, and
-  `hooks/*.sh` == `src/okl/scaffold/hooks/*.sh`. The scaffold copies are what consumers
+  `.github/workflows/okl-verify.yml` == `src/okl/scaffold/ci/okl-verify.yml`,
+  `hooks/*.sh` == `src/okl/scaffold/hooks/*.sh`, and
+  `gates/*.sh` == `src/okl/scaffold/gates/*.sh`. The scaffold copies are what consumers
   receive; the repo copies are the dogfood. Edit ONE, copy to the others in the same
   change — `tests/test_scaffold.py::test_mirror_files_identical` fails otherwise.
 - **ruff `E702` is ignored deliberately** (semicolon one-liners): the tests use a

{org_knowledge_layer-0.3.1 → org_knowledge_layer-0.4.0}/CHANGELOG.md

@@ -1,5 +1,54 @@
 # Changelog
 
+## 0.4.0
+
+### Behaviour changes worth reading before upgrading
+
+- **Stack tags now filter exclusively.** A record naming a stack (`dotnet`, `react`,
+  `geospatial`, `python`, `python-rag`) is only shown to a repo that declared that stack
+  in its `interests`. Previously any shared tag let it through, so a rule tagged
+  `dotnet,method` reached every repo interested in `method` — a subject 75 records carry.
+  **If you declare `interests`, expect fewer records after upgrading.** That is the point,
+  but it is a change in what your briefings contain. Repos that declare no interests are
+  unaffected, and untagged records still always pass.
+- **`symptom` and `fix` are now searchable.** They were not, which meant a record written
+  the way the docs tell you to write it — short title, the distinguishing words in the
+  symptom — could not be retrieved at all. Existing stores rebuild their index on first
+  open; you do not need to re-record anything.
+
+### Added
+
+- **`okl dedup`** reports near-duplicate records for review. Lexical and explainable:
+  per-field weighted Jaccard over title, symptom and fix, IDF-weighted from your own
+  corpus. It never merges or drops anything — the measured score bands for true
+  paraphrases and for distinct-but-related records overlap, so the call is a person's.
+  The same check runs as an advisory when importing an agent-proposed pack.
+- **`/seed-from-docs`** mines the specs, ADRs and rules files you already wrote into typed
+  records. Built around one distinction: a record is a standing instruction that outlives
+  the work item it came from, so "deep offsets use keyset pagination" belongs and "add
+  pagination to /orders this sprint" does not.
+- A pack declaring `_proposed_by` is refused unless every node carries a `found_by`
+  citation, so the rule the seeding commands state is enforced at import rather than
+  remembered by a reviewer.
+
+### Fixed
+
+- `Client._remote_url` validates the URL scheme once. A `service_url` from config could
+  name `file://`, turning a remote read into a local file read.
+- `OKLUnreachable` is now `OKLUnreachableError`, with the old name kept as an alias so
+  existing `except` clauses still work.
+- Drift timestamps are timezone-aware; `utcfromtimestamp` is deprecated from Python 3.12
+  and returned a naive datetime that read as local time when compared across machines.
+
+### Internal
+
+- `_Backend` is a `typing.Protocol` whose docstring states the behavioural contract, with
+  one conformance test both backends run — the defect it guards (Postgres satisfying every
+  signature while running an unranked match) was invisible to signatures alone.
+- mypy, and ruff widened from 6 rule families to 15 including security and complexity,
+  both wired into CI alongside a secret scan, the method gates and a coverage floor.
+
+
 ## 0.3.1
 
 ### Security

{org_knowledge_layer-0.3.1 → org_knowledge_layer-0.4.0}/CLAUDE.md

@@ -31,8 +31,9 @@ okl drift                          # rules whose governed source changed after v
 ## Rules that are enforced (and why)
 
 - **Mirror files are byte-identical, test-enforced**: `ci/okl-verify.yml` ==
-  `.github/workflows/okl-verify.yml` == `src/okl/scaffold/ci/okl-verify.yml`, and
-  `hooks/*.sh` == `src/okl/scaffold/hooks/*.sh`. The scaffold copies are what consumers
+  `.github/workflows/okl-verify.yml` == `src/okl/scaffold/ci/okl-verify.yml`,
+  `hooks/*.sh` == `src/okl/scaffold/hooks/*.sh`, and
+  `gates/*.sh` == `src/okl/scaffold/gates/*.sh`. The scaffold copies are what consumers
   receive; the repo copies are the dogfood. Edit ONE, copy to the others in the same
   change — `tests/test_scaffold.py::test_mirror_files_identical` fails otherwise.
 - **ruff `E702` is ignored deliberately** (semicolon one-liners): the tests use a

org_knowledge_layer-0.3.1/README.md → org_knowledge_layer-0.4.0/PKG-INFO

@@ -1,3 +1,37 @@
+Metadata-Version: 2.5
+Name: org-knowledge-layer
+Version: 0.4.0
+Summary: Org Knowledge Layer — an installable sixth surface that carries encoded engineering lessons across repos.
+Author: Joshua Dell
+License: MIT
+License-File: LICENSE
+Keywords: agentic-coding,ai-engineering,encoding-loop,knowledge-layer,mcp
+Requires-Python: >=3.10
+Provides-Extra: all
+Requires-Dist: fastapi>=0.110; extra == 'all'
+Requires-Dist: mcp>=1.2; extra == 'all'
+Requires-Dist: psycopg[binary]>=3.1; extra == 'all'
+Requires-Dist: pydantic>=2; extra == 'all'
+Requires-Dist: uvicorn>=0.29; extra == 'all'
+Provides-Extra: dev
+Requires-Dist: fastapi>=0.110; extra == 'dev'
+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: ruff==0.16.5; extra == 'dev'
+Requires-Dist: uvicorn>=0.29; extra == 'dev'
+Provides-Extra: mcp
+Requires-Dist: mcp>=1.2; extra == 'mcp'
+Provides-Extra: postgres
+Requires-Dist: psycopg[binary]>=3.1; extra == 'postgres'
+Provides-Extra: service
+Requires-Dist: fastapi>=0.110; extra == 'service'
+Requires-Dist: pydantic>=2; extra == 'service'
+Requires-Dist: uvicorn>=0.29; extra == 'service'
+Description-Content-Type: text/markdown
+
 # okl — a shared knowledge layer for AI-assisted engineering
 
 > A small database of the specific lessons a codebase has learned — the bugs it
@@ -46,6 +80,17 @@ Two things ship in the package. They are not coequal:
   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.
+
+  It is worth being precise about what that store fills up with, because "lessons a
+  codebase has learned" invites the picture of a bug database. In the 161-record corpus
+  in [seed/](seed/) it is mostly not that: **90 Rules, 20 Decisions and 7 Gates against
+  34 Defects** — conventions the code follows and trade-offs already settled, not a
+  ledger of things that broke. Count it yourself:
+
+  ```bash
+  python3 -c "import json,glob,collections; c=collections.Counter(
+    n['type'] for f in glob.glob('seed/*.json') for n in json.load(open(f))['nodes']); print(c)"
+  ```
 - **`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
@@ -163,6 +208,8 @@ with receipts, not a benchmark.
 
 ## How it works
 
+<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%">
+
 ### The mental model
 
 `okl` stores small, typed **notes** and the **links** between them.
@@ -258,6 +305,59 @@ pip install "org-knowledge-layer[mcp]"        # MCP server for Claude Code / Cur
 pip install "org-knowledge-layer[all]"
 ```
 
+## What it costs, and how to turn it down
+
+Installing okl is not free. It is worth knowing exactly what you are signing up for
+before you wire it into every prompt, and every number below was measured on this repo's
+own 199-record store rather than estimated.
+
+**Per prompt, once the hook is installed:**
+
+| | |
+|---|---|
+| Latency | **~0.11s** — one local SQLite query, no network in local mode |
+| Context | **~2,300 tokens** at the default `--limit 12`, down to **~250** at `--format actions --limit 3` |
+
+**Per session:** the Stop hook interrupts once at the end to ask what was learned. It
+blocks the first stop only, and answering it is the whole write side of the loop.
+
+**In your repo:** `okl init` writes `.okl/` (config, the local database, a `.gitignore`
+covering both) and, if `.claude/` exists, two hook scripts plus their registration. It
+also installs `.github/workflows/okl-verify.yml`, which runs the drift gate on every PR.
+`okl scaffold` is separate and optional — nothing installs it unless you ask.
+
+### The knobs, cheapest first
+
+```bash
+okl check --task "..." --format actions   # imperatives only, ~60% smaller
+okl check --task "..." --limit 3          # fewer records; the briefing says how many it trimmed
+okl init --interests "python,security"    # drop records tagged for stacks you do not use
+```
+
+- **`--format actions`** is the single biggest saving and loses the least: you keep every
+  "when you see X → do Y" and drop the explanatory prose.
+- **`--limit N`** caps how many records are drawn on. The briefing always reports what it
+  trimmed, so a short briefing can never quietly hide a miss.
+- **`interests`** is the one to reach for on a mature shared store. Stack tags filter
+  exclusively — declaring `python` means records tagged `dotnet` stay out even when they
+  share a subject tag with something you asked for.
+- **Scope records `repo:` rather than `org`** when a lesson is local. Org scope is a claim
+  that every project in the organization should see it, and it costs every project's
+  budget to be wrong about that.
+
+### Turning parts off
+
+The hooks are registered in `.claude/settings.json`; delete the entry to stop one firing.
+The pre-task hook is the read side and the Stop hook is the write side, and they are
+independent — running the read without the write is a reasonable way to start.
+
+Nothing is load-bearing on the hooks: `okl check` and `okl record` work from the terminal,
+from CI, and through the MCP server whether or not any hook is installed.
+
+To remove okl from a repo entirely, delete `.okl/`, the two hook scripts and their entries
+in `.claude/settings.json`, and `.github/workflows/okl-verify.yml`. Nothing else was
+written, and nothing outside that repo was touched.
+
 ## Wire a repo
 
 ```bash
@@ -371,7 +471,7 @@ okl metric           # recurrence-after-arming: defect classes that came back in
 
 ## Subagents and small context budgets
 
-A full briefing costs roughly **4,400 tokens** — fine for a main session with a large
+A full briefing costs roughly **2,300 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

org_knowledge_layer-0.3.1/PKG-INFO → org_knowledge_layer-0.4.0/README.md

@@ -1,35 +1,3 @@
-Metadata-Version: 2.5
-Name: org-knowledge-layer
-Version: 0.3.1
-Summary: Org Knowledge Layer — an installable sixth surface that carries encoded engineering lessons across repos.
-Author: Joshua Dell
-License: MIT
-License-File: LICENSE
-Keywords: agentic-coding,ai-engineering,encoding-loop,knowledge-layer,mcp
-Requires-Python: >=3.10
-Provides-Extra: all
-Requires-Dist: fastapi>=0.110; extra == 'all'
-Requires-Dist: mcp>=1.2; extra == 'all'
-Requires-Dist: psycopg[binary]>=3.1; extra == 'all'
-Requires-Dist: pydantic>=2; extra == 'all'
-Requires-Dist: uvicorn>=0.29; extra == 'all'
-Provides-Extra: dev
-Requires-Dist: fastapi>=0.110; extra == 'dev'
-Requires-Dist: httpx>=0.27; extra == 'dev'
-Requires-Dist: pydantic>=2; extra == 'dev'
-Requires-Dist: pytest>=8; extra == 'dev'
-Requires-Dist: ruff>=0.8; extra == 'dev'
-Requires-Dist: uvicorn>=0.29; extra == 'dev'
-Provides-Extra: mcp
-Requires-Dist: mcp>=1.2; extra == 'mcp'
-Provides-Extra: postgres
-Requires-Dist: psycopg[binary]>=3.1; extra == 'postgres'
-Provides-Extra: service
-Requires-Dist: fastapi>=0.110; extra == 'service'
-Requires-Dist: pydantic>=2; extra == 'service'
-Requires-Dist: uvicorn>=0.29; extra == 'service'
-Description-Content-Type: text/markdown
-
 # okl — a shared knowledge layer for AI-assisted engineering
 
 > A small database of the specific lessons a codebase has learned — the bugs it
@@ -78,6 +46,17 @@ Two things ship in the package. They are not coequal:
   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.
+
+  It is worth being precise about what that store fills up with, because "lessons a
+  codebase has learned" invites the picture of a bug database. In the 161-record corpus
+  in [seed/](seed/) it is mostly not that: **90 Rules, 20 Decisions and 7 Gates against
+  34 Defects** — conventions the code follows and trade-offs already settled, not a
+  ledger of things that broke. Count it yourself:
+
+  ```bash
+  python3 -c "import json,glob,collections; c=collections.Counter(
+    n['type'] for f in glob.glob('seed/*.json') for n in json.load(open(f))['nodes']); print(c)"
+  ```
 - **`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
@@ -195,6 +174,8 @@ with receipts, not a benchmark.
 
 ## How it works
 
+<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%">
+
 ### The mental model
 
 `okl` stores small, typed **notes** and the **links** between them.
@@ -290,6 +271,59 @@ pip install "org-knowledge-layer[mcp]"        # MCP server for Claude Code / Cur
 pip install "org-knowledge-layer[all]"
 ```
 
+## What it costs, and how to turn it down
+
+Installing okl is not free. It is worth knowing exactly what you are signing up for
+before you wire it into every prompt, and every number below was measured on this repo's
+own 199-record store rather than estimated.
+
+**Per prompt, once the hook is installed:**
+
+| | |
+|---|---|
+| Latency | **~0.11s** — one local SQLite query, no network in local mode |
+| Context | **~2,300 tokens** at the default `--limit 12`, down to **~250** at `--format actions --limit 3` |
+
+**Per session:** the Stop hook interrupts once at the end to ask what was learned. It
+blocks the first stop only, and answering it is the whole write side of the loop.
+
+**In your repo:** `okl init` writes `.okl/` (config, the local database, a `.gitignore`
+covering both) and, if `.claude/` exists, two hook scripts plus their registration. It
+also installs `.github/workflows/okl-verify.yml`, which runs the drift gate on every PR.
+`okl scaffold` is separate and optional — nothing installs it unless you ask.
+
+### The knobs, cheapest first
+
+```bash
+okl check --task "..." --format actions   # imperatives only, ~60% smaller
+okl check --task "..." --limit 3          # fewer records; the briefing says how many it trimmed
+okl init --interests "python,security"    # drop records tagged for stacks you do not use
+```
+
+- **`--format actions`** is the single biggest saving and loses the least: you keep every
+  "when you see X → do Y" and drop the explanatory prose.
+- **`--limit N`** caps how many records are drawn on. The briefing always reports what it
+  trimmed, so a short briefing can never quietly hide a miss.
+- **`interests`** is the one to reach for on a mature shared store. Stack tags filter
+  exclusively — declaring `python` means records tagged `dotnet` stay out even when they
+  share a subject tag with something you asked for.
+- **Scope records `repo:` rather than `org`** when a lesson is local. Org scope is a claim
+  that every project in the organization should see it, and it costs every project's
+  budget to be wrong about that.
+
+### Turning parts off
+
+The hooks are registered in `.claude/settings.json`; delete the entry to stop one firing.
+The pre-task hook is the read side and the Stop hook is the write side, and they are
+independent — running the read without the write is a reasonable way to start.
+
+Nothing is load-bearing on the hooks: `okl check` and `okl record` work from the terminal,
+from CI, and through the MCP server whether or not any hook is installed.
+
+To remove okl from a repo entirely, delete `.okl/`, the two hook scripts and their entries
+in `.claude/settings.json`, and `.github/workflows/okl-verify.yml`. Nothing else was
+written, and nothing outside that repo was touched.
+
 ## Wire a repo
 
 ```bash
@@ -403,7 +437,7 @@ okl metric           # recurrence-after-arming: defect classes that came back in
 
 ## Subagents and small context budgets
 
-A full briefing costs roughly **4,400 tokens** — fine for a main session with a large
+A full briefing costs roughly **2,300 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

org_knowledge_layer-0.4.0/ci/check-diagram-figures.sh

@@ -0,0 +1,82 @@
+#!/usr/bin/env bash
+# Every figure a committed diagram publishes must trace to a committed receipt.
+#
+# The sixth-surface diagram rendered "50% → 6%" and "75% → 8%" under a heading reading
+# "MEASURED (held-fixed A/B, blind judge≠generator)" for weeks, in the repo and on a
+# public site. Those are the 2026-07-17 numbers that REPORT.md §7 quarantines as
+# historical: the raw artifacts were never checked in, so they are not reproducible. The
+# site's own prose cited the receipted figures right beside the image, so the page
+# contradicted itself and a reader had no way to tell which was real.
+#
+# It survived because the drift stamp on the diagram record was earned by grepping for a
+# couple of expected strings. "Some expected text is present" is not "no unsupported
+# claim is present" — only the second is worth a verification stamp.
+#
+# Reads the repo, not the working tree, per the audit rule in CLAUDE.md: an uncommitted
+# edit must not be able to pass or fail an audit that main would answer differently.
+set -euo pipefail
+cd "$(git rev-parse --show-toplevel)"
+
+# A marker file, because the checks run inside a `while read` subshell and a variable set
+# there cannot reach this scope.
+work=$(mktemp -d)
+trap 'rm -rf "$work"' EXIT
+
+# Every diagram under docs/, rather than a hard-coded path: a diagram added later is
+# covered the day it lands, not the day someone remembers to extend this file.
+#
+# `while read` rather than `mapfile`, which is bash 4+. macOS ships bash 3.2, so mapfile
+# would have passed on ubuntu CI and failed for anyone running it locally — the shape of
+# bug this repo already keeps a rule about.
+git ls-files 'docs/*.excalidraw' | while IFS= read -r src; do
+  svg="${src%.excalidraw}.svg"
+  echo "-- $src"
+
+  # 1. Every receipt the diagram names is committed. A diagram that shows a percentage
+  #    while naming no receipt at all is the original failure and fails here too.
+  named=$(git show "HEAD:$src" | grep -oE 'ab-[0-9]{8}-[0-9]{4}' | sort -u || true)
+  if [ -z "$named" ]; then
+    if git show "HEAD:$src" | grep -qE '[0-9]+ ?%'; then
+      echo "   FAIL: shows a percentage but names no receipt"
+      touch "$work/fail"
+    else
+      echo "   ok: publishes no figures"
+    fi
+  fi
+  for r in $named; do
+    if git ls-files --error-unmatch "evals/results/$r.json" >/dev/null 2>&1; then
+      echo "   ok: $r has a committed receipt"
+    else
+      echo "   FAIL: cites $r, which is not committed under evals/results/"
+      touch "$work/fail"
+    fi
+  done
+
+  # 2. The figures REPORT.md §7 marks as historical must never appear as current claims.
+  for q in '50% → 6%' '75% → 8%'; do
+    if git show "HEAD:$src" | grep -qF "$q"; then
+      echo "   FAIL: publishes '$q', quarantined as historical in REPORT.md §7"
+      touch "$work/fail"
+    fi
+  done
+
+  # 3. The SVG is a render of the source, so it must carry the same receipts. This is
+  #    what catches an edited .excalidraw whose SVG was never regenerated — the image is
+  #    what people actually read, and it is the artifact that ships to the site.
+  if git ls-files --error-unmatch "$svg" >/dev/null 2>&1; then
+    for r in $named; do
+      if ! git show "HEAD:$svg" | grep -qF "$r"; then
+        echo "   FAIL: $svg is missing $r — re-render it from the source"
+        touch "$work/fail"
+      fi
+    done
+  else
+    echo "   FAIL: $svg is not committed; the source has no published render"
+    touch "$work/fail"
+  fi
+done
+
+if [ -e "$work/fail" ]; then
+  exit 1
+fi
+echo "DIAGRAM_FIGURES_RECEIPTED"

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

@@ -50,3 +50,10 @@ seed-file comments ("eval-integrity lessons are org-scoped") and the scaffold's
 
 - 2026-07-21: `messaging` added to the vocabulary during the .NET platform canon import — the
   broker/queue/event-driven rules fit no existing subject.
+- 2026-09-02: `python` added. A code review of this repo found 190 records of which 75 were
+  tagged `dotnet` — CQRS, aggregates, outbox, DI scopes — governing a Python codebase that has
+  none of those things, while okl's own conventions had no subject to file under. `python-rag`
+  was the nearest existing tag and is wrong: it is a stack tag for one service's retrieval
+  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.