observed-knowledge-ledger 0.7.2__tar.gz → 0.7.4__tar.gz

{observed_knowledge_ledger-0.7.2 → observed_knowledge_ledger-0.7.4}/.claude/agents/architecture-reviewer.md

@@ -12,6 +12,8 @@ skills:
 
 You are a reviewer, not an implementer. You read the change and judge it against the encoded body —
 you do not rewrite it. Your output is a checklist verdict with specific file:line findings.
+Needs the method kit that `okl scaffold .` installs (`registries/`, `.claude/rules/`, the
+`encoding-loop` skill); where it is missing, say which checks you could not run.
 
 ## Before you start
 1. Run `okl check --task "<one-line summary of the change under review>"` and treat the returned
@@ -23,7 +25,7 @@ you do not rewrite it. Your output is a checklist verdict with specific file:lin
   with exactly one implementation and no test substitution and no concrete second impl on the
   roadmap? If so, flag it as speculative — the concrete class should be used directly.
 - **Assert-from-memory** — does any spec/config/scaffold claim something is "correct"/"valid"
-  without a mechanical `validate` step? Flag it; this is the #14-class defect.
+  without a mechanical `validate` step? Flag it; this is the assert-from-memory defect class.
 - **Retracted claim restated** — does any prose restate a claim in `registries/RETRACTIONS.md`
   without also retracting it? Fail.
 - **Resurrected identifier** — does the diff reintroduce anything in `registries/tombstones.txt`? Fail.

observed_knowledge_ledger-0.7.4/.claude/commands/record.md

@@ -0,0 +1,63 @@
+---
+description: Turn what this session just learned (a decision, a convention, a bug fixed) into an okl lesson — drafted from the conversation, recorded after you confirm.
+argument-hint: "[what to record, in your own words — optional]"
+---
+
+# /record — add a lesson to the store from plain language
+
+The person wants to keep something so the next session does not relearn it. They may
+have said it in `$ARGUMENTS`; if that is empty, take it from the last few turns of this
+conversation (the bug just fixed, the choice just made, the convention just followed).
+
+## 1. Draft it
+
+Pick the type from what it is:
+
+- **Decision** — chosen on purpose; should not be quietly reversed. Body starts `why:`.
+- **Rule** — a convention. Needs a `symptom` (what an agent would see or do that should
+  trigger it) and a `fix` (what to do instead). Cause goes in `body`.
+- **Defect** — a bug that was fixed. `symptom` is how it showed up, `fix` is the repair,
+  `body` is the cause.
+
+Then fill in, from evidence in this session only:
+
+- **id** — a short kebab-case key (`discount-single-use`). Reusing an id updates that
+  lesson; search first (`okl_search`) and reuse the id if this refines an existing one.
+- **scope** — `repo` unless the lesson is true in every codebase that shares the store.
+  If unsure, `repo`.
+- **files** — the files the lesson governs, if it governs specific code. This is what
+  makes `okl drift` notice when that code changes. Omit for pure decisions.
+- **tags** — only from the vocabulary `okl_record` names; omit if none fits.
+- **applies_to** — leave unset. Only set it if the lesson is *false* off one stack.
+
+Do not invent a cause, a number or a file you have not seen in this session.
+
+## 2. Show it, then record it
+
+Show the draft as a short block (type, id, scope, title, symptom → fix, files) and ask
+the person to confirm or correct it. On a yes, record it with the `okl_record` MCP tool.
+If that tool is not available, run the equivalent `okl record --type … --id … --scope …`
+command instead.
+
+## 3. Decide how hard it must be enforced
+
+Use the softest level that holds, and say which you chose:
+
+- **Briefing only** — every lesson reaches the per-task briefing. Most need nothing more.
+- **Watched by CI** — the lesson governs specific code (`files` is set). Offer to prove it
+  with a check that fails when the lesson is broken:
+
+  ```bash
+  okl verify <id> --run "<that check>" --expect "<text its passing output contains>"
+  ```
+
+  CI's drift gate then goes red when that code changes, until the check is re-run. Remind
+  the person to commit `okl-drift.json` after the verify. Never mark a lesson verified any
+  other way.
+- **Build-breaking** — the same mistake has happened before, or it is costly when it
+  happens (security, data loss, a published number). Propose a test or CI check that
+  fails the build; a sterner lesson will not stop a repeat.
+- **Always-on** — only if every session needs it regardless of task, propose a line for
+  `CLAUDE.md` / `AGENTS.md`. This is rare; the briefing already delivers the rest.
+
+The `encoding-loop` skill has the full table.

{observed_knowledge_ledger-0.7.2 → observed_knowledge_ledger-0.7.4}/.claude/hooks/stop-okl-encode.sh

@@ -1,5 +1,5 @@
 #!/usr/bin/env bash
-# okl-fingerprint: sha256:5c21a4ef0db1d9f64175040ae313e04c97cf6008654c8941bd5864c946708867
+# okl-fingerprint: sha256:330e6e866e80cbd1d07bb8c4425e9473e1df4e78126d01f9a1ea72eaf249783a
 # Stop hook — the write-side mechanical catch for the encoding loop.
 #
 # The read side (okl check) is enforced by the UserPromptSubmit hook; nothing enforced the WRITE
@@ -27,7 +27,23 @@ fi
 # the operator makes explicitly, never a fallback the hook takes on its own.
 case ",${OKL_DISABLED_HOOKS:-}," in *,encode,*) exit 0 ;; esac
 
-# Same resolver as pretooluse-okl-check.sh (env → pinned config → PATH → python3 -m okl);
+# Not enrolled: step aside. okl's Claude Code plugin is installed per user, so these hooks
+# run in EVERY repo the user opens, and most were never set up with `okl init`. There the
+# pre-task hook blocked every prompt as "OKL NOT CONFIGURED" and the Stop hook asked
+# "what did we learn?" of repos with no store to record into (found by a docs audit,
+# 2026-09-29, before any user hit it). Only when Claude Code names the project: with no
+# CLAUDE_PROJECT_DIR the hook cannot tell an unenrolled repo from a session that drifted
+# out of an enrolled one, and fail-closed still wins there.
+if [ -n "${CLAUDE_PROJECT_DIR:-}" ] && [ -z "${OKL_SERVICE_URL:-}${OKL_DATABASE_URL:-}" ]; then
+  enrolled=0; d="$PWD"
+  while [ "$d" != "/" ]; do
+    if [ -f "$d/.okl/config.json" ]; then enrolled=1; break; fi
+    d=$(dirname "$d")
+  done
+  [ "$enrolled" = 1 ] || exit 0
+fi
+
+# Same resolver as userpromptsubmit-okl-check.sh (env → pinned config → PATH → python3 -m okl);
 # the reminder is best-effort, so an unresolvable okl silently disables it rather than blocking.
 # A layer is used only if its command can actually run. A pinned path goes stale when the
 # venv that held it is recreated; running it anyway produced the shell's own "No such file
@@ -117,6 +133,15 @@ silently reversed? If yes, record it now. Three independent axes, each chosen de
     --id "<stable-key>" --title "..." --symptom "..." --body "cause: ..." --fix "..." \
     [--applies-to <stack>]   # ONLY for a genuinely framework-bound lesson
 
+  Then decide how hard it must be enforced (softest that holds):
+  - Every lesson reaches the per-task briefing; most need nothing more.
+  - Governs specific code? Add --files "<paths>" and prove it:
+      okl verify <id> --run "<check that fails if broken>" --expect "<success text>"
+    CI's drift gate then goes red when that code changes.
+  - Broken more than once, or costly when broken? Propose a test or CI check that
+    fails the build, rather than a sterner lesson.
+  - Needed in every session regardless of task? Only then CLAUDE.md / AGENTS.md.
+
   --id is what makes the write idempotent, and leaving it off is the common mistake.
   Without it every record is minted a fresh random id, so the same lesson recorded in two
   sessions becomes two rows, which `okl dedup` will report but cannot remove: there is no

{observed_knowledge_ledger-0.7.2/src/okl/scaffold → observed_knowledge_ledger-0.7.4/.claude}/hooks/userpromptsubmit-okl-check.sh

@@ -1,5 +1,5 @@
 #!/usr/bin/env bash
-# okl-fingerprint: sha256:cb169accaa93f9e91efb99027845847d17497de9c68e1b88d76dc7beef55780b
+# okl-fingerprint: sha256:7bd1125f0adc50f1b805a80228727b54b093ec0b8c974a3d1da3838cab3f762b
 # UserPromptSubmit hook — inject the org's relevant lessons into the model's context
 # BEFORE it starts the task. This event is the only correct one for delivery: its stdout
 # (exit 0) is added to Claude's context, and its stdin carries the actual prompt text, so
@@ -32,6 +32,22 @@ fi
 # the operator makes explicitly, never a fallback the hook takes on its own.
 case ",${OKL_DISABLED_HOOKS:-}," in *,briefing,*) exit 0 ;; esac
 
+# Not enrolled: step aside. okl's Claude Code plugin is installed per user, so these hooks
+# run in EVERY repo the user opens, and most were never set up with `okl init`. There the
+# pre-task hook blocked every prompt as "OKL NOT CONFIGURED" and the Stop hook asked
+# "what did we learn?" of repos with no store to record into (found by a docs audit,
+# 2026-09-29, before any user hit it). Only when Claude Code names the project: with no
+# CLAUDE_PROJECT_DIR the hook cannot tell an unenrolled repo from a session that drifted
+# out of an enrolled one, and fail-closed still wins there.
+if [ -n "${CLAUDE_PROJECT_DIR:-}" ] && [ -z "${OKL_SERVICE_URL:-}${OKL_DATABASE_URL:-}" ]; then
+  enrolled=0; d="$PWD"
+  while [ "$d" != "/" ]; do
+    if [ -f "$d/.okl/config.json" ]; then enrolled=1; break; fi
+    d=$(dirname "$d")
+  done
+  [ "$enrolled" = 1 ] || exit 0
+fi
+
 # Resolve how to invoke okl (env → pinned config → PATH → python3 -m okl); hooks run in
 # whatever environment the harness spawns, which often lacks the venv/pipx bin dir.
 # A layer is used only if its command can actually run. A pinned path goes stale when the
@@ -101,8 +117,18 @@ TASK="${OKL_TASK:-${prompt:-$(git log -1 --pretty=%s 2>/dev/null || echo 'genera
 # No guessable fallback path: a fixed name under /tmp could be pre-planted as a symlink by
 # another local user. Without a private temp file the reason is lost, not the check.
 errf=$(mktemp 2>/dev/null) || errf=""
-out=$($OKL check --task "$TASK" --format agent 2>"${errf:-/dev/null}")
+# --format hook: the briefing for the model's context plus one line the person can see,
+# as the JSON Claude Code reads from a UserPromptSubmit hook. Without that line nobody
+# could tell okl helping from okl doing nothing.
+out=$($OKL check --task "$TASK" --format hook 2>"${errf:-/dev/null}")
 rc=$?   # read here: after an if-block, $? is the if's own status, not okl's
+if [ "$rc" -eq 2 ] && [ -n "$errf" ] && grep -q "invalid choice" "$errf" 2>/dev/null; then
+  # An okl older than this hook has no --format hook. The plugin updates from main and the
+  # CLI only when upgraded, so the two can differ: brief the old way rather than block.
+  : > "$errf"
+  out=$($OKL check --task "$TASK" --format agent 2>"${errf:-/dev/null}")
+  rc=$?
+fi
 if [ "$rc" -eq 0 ]; then
   [ -n "$errf" ] && rm -f "$errf"
   printf '%s\n' "$out"      # stdout → the model's context

{observed_knowledge_ledger-0.7.2/src/okl/scaffold/claude → observed_knowledge_ledger-0.7.4/.claude}/skills/encoding-loop/SKILL.md

@@ -16,7 +16,7 @@ A trigger surfaced a candidate rule. The response is always the same two moves.
 | 2 | `.claude/rules/<area>.md` with `paths:` glob | scoped to a file category (loads only in context) |
 | 3 | `.claude/skills/` or `.claude/commands/` | a multi-step procedure with real logic |
 | 4 | `.coderabbit.yaml` path_instructions / `architecture-reviewer` checklist | catch at PR-review time |
-| 5 | a gate in `gates/` + CI | mechanical, build-breaking — for rules that keep being broken |
+| 5 | a test or a CI check (`gates/` if you ran `okl scaffold`) | mechanical, build-breaking — for rules that keep being broken |
 
 Default to the *softest* surface that could hold the rule. **Promote down (toward 5) only as it
 earns it** — a rule that keeps being violated moves to a sterner tier, not a sterner paragraph.
@@ -40,12 +40,16 @@ okl verify <stable-key> --run "<a check that fails if the lesson is broken>" --e
   reports but cannot remove, there being no delete subcommand. Where a repo keeps its lessons in
   a seed file, use the id that file derives, `seed:<seed-file-stem>:<key>`, so a later
   `okl seed` upserts the same row.
+- **`--files`** — the code the lesson governs. With it, and once `okl verify` has passed,
+  CI's drift gate goes red whenever that code changes until the check is re-run. This is
+  what sits between tier 1 and a gate: watched, but not build-breaking on its own.
 - **`scope=org`** — a fact about the world: prior art, an API contract, a data-source gotcha, a
   portable gate. It will surface in every connected repo's `okl check`.
 - **`scope=repo`** — a quirk true only of this codebase. Stays local.
 
 If the finding retracts a prior claim, also add it to `registries/RETRACTIONS.md`; if it retires an
-identifier, add it to `registries/tombstones.txt`. The CI gates then fail any doc that contradicts.
+identifier, add it to `registries/tombstones.txt`. The CI gates then fail any doc that restates
+the quoted retracted claim verbatim, or reintroduces the tombstoned identifier.
 
 ## 3. Verify the gate (if you made one)
 

{observed_knowledge_ledger-0.7.2 → observed_knowledge_ledger-0.7.4}/.claude-plugin/marketplace.json

@@ -9,7 +9,7 @@
     {
       "name": "okl",
       "source": "./",
-      "description": "Observed Knowledge Ledger: the pre-task briefing and end-of-session hooks, MCP tools and seeding commands. Requires the okl CLI (pipx install 'observed-knowledge-ledger[mcp]')."
+      "description": "Observed Knowledge Ledger: the pre-task briefing and end-of-session hooks, MCP tools and seeding commands. Requires the okl CLI (pipx install 'observed-knowledge-ledger[mcp]') and `okl init` in each repo to brief (or OKL_SERVICE_URL); repos without it are left alone."
     }
   ]
 }

{observed_knowledge_ledger-0.7.2 → observed_knowledge_ledger-0.7.4}/.claude-plugin/plugin.json

@@ -1,14 +1,16 @@
 {
   "name": "okl",
-  "version": "0.7.2",
-  "description": "Observed Knowledge Ledger: lessons your coding agents can trust. A pre-task briefing hook, an end-of-session 'what did we learn?' hook, the okl MCP tools, and the seeding commands. Needs the okl CLI with the MCP extra: pipx install 'observed-knowledge-ledger[mcp]'",
+  "version": "0.7.4",
+  "description": "Observed Knowledge Ledger: lessons your coding agents can trust. A pre-task briefing hook, an end-of-session 'what did we learn?' hook, the okl MCP tools, the /record and seeding commands, and the encoding-loop skill. Needs the okl CLI (pipx install 'observed-knowledge-ledger[mcp]'), and `okl init` in each repo to brief (or OKL_SERVICE_URL); repos without it are left alone.",
   "author": { "name": "Joshua Dell", "url": "https://github.com/emeraldleaf/okl" },
   "hooks": "./hooks/hooks.json",
   "mcpServers": "./.mcp.json",
   "commands": [
     "./src/okl/scaffold/claude/commands/check-rules.md",
+    "./src/okl/scaffold/claude/commands/record.md",
     "./src/okl/scaffold/claude/commands/seed-from-codebase.md",
     "./src/okl/scaffold/claude/commands/seed-from-docs.md"
   ],
+  "skills": ["./src/okl/scaffold/claude/skills/encoding-loop"],
   "agents": ["./src/okl/scaffold/claude/agents/architecture-reviewer.md"]
 }

{observed_knowledge_ledger-0.7.2 → observed_knowledge_ledger-0.7.4}/.gitignore

@@ -21,3 +21,6 @@ e2e/
 .github/instructions/codacy.instructions.md
 okl.db-wal
 okl.db-shm
+
+# test output
+.coverage

{observed_knowledge_ledger-0.7.2 → observed_knowledge_ledger-0.7.4}/AGENTS.md

@@ -27,8 +27,7 @@ and editing `KNOWN_TAGS` changes the floor every store ships with.
   verification left uncommitted fails CI. Verifying before the code commit re-drifts.
   Give a rule `--files` only when CI does not already run its check (#39).
 - The local store (`.okl/okl.db`, gitignored) should hold all 11 seed files plus
-  recorded nodes; `okl seed seed/` loads the `*-defects.json` set, while
-  `dotnet-{canon,decisions,review-surfaces}.json` and `frontend-canon.json` load explicitly.
+  recorded nodes; `okl seed seed/` (or `okl seed --all`) loads all 11 packs.
 
 ## Commands
 
@@ -44,7 +43,8 @@ okl drift                          # rules whose governed source changed after v
 - **Mirror files are byte-identical, test-enforced**: `ci/okl-verify.yml` ==
   `.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
+  `gates/*.sh` == `src/okl/scaffold/gates/*.sh`; `.claude/hooks`, `.claude/commands/record.md`
+  and `.claude/skills/encoding-loop` mirror theirs too. 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
@@ -67,7 +67,7 @@ okl drift                          # rules whose governed source changed after v
 
 `src/okl/` is the package (store/core/client/cli/service/mcp + scaffold templates);
 `seed/` is the curated 161-node corpus (real lessons, real project names — deliberate);
-`evals/` is the A/B harness and receipts; `docs/posts/` is the 3-part write-up;
+`evals/` is the A/B harness and receipts; `docs/posts/` is the 4-part write-up;
 `e2e/` (gitignored) holds scratch repos for end-to-end loop tests.
 
 This file stays lean — always-on rules only. Everything conditionally relevant belongs

{observed_knowledge_ledger-0.7.2 → observed_knowledge_ledger-0.7.4}/CHANGELOG.md

@@ -1,5 +1,41 @@
 # Changelog
 
+## 0.7.4
+
+- **`okl verify` / `okl reverify` treat a timeout as a failed check.** A check that
+  outlived `--timeout` raised an uncaught error, so `okl reverify` stopped in a traceback
+  and every later lesson went unchecked.
+- **`okl_search` results lead with the lesson id**, so an agent can pass it to
+  `okl_record` to update the lesson instead of adding a near-duplicate.
+- `.coverage` is no longer tracked.
+
+## 0.7.3
+
+- **A first run that works with no choices.** `okl init` detects the stack and sets
+  interests from it, and seeds an empty local store with 20 portable starter lessons plus
+  the bundled packs for that stack, so the first prompt is briefed. `--no-seed` opts out.
+  Starter lessons are references into the packs, so importing a full pack later updates
+  the same rows.
+- **You can see okl working.** Each briefed prompt shows one line, *okl · briefed N
+  lesson(s): …*, via `okl check --format hook`; `OKL_QUIET=1` hides it. The hook falls back
+  to the plain briefing if the installed okl predates the format.
+- **Record by saying it.** The `okl_record` MCP tool takes `id` (re-recording updates the
+  lesson) and `applies_to`, so any MCP agent can record what the CLI can; a new `/record`
+  command drafts a lesson from the conversation and records it once you confirm. The
+  getting-started guide leads with this, covers other agents, and keeps the CLI as the
+  mechanism underneath.
+- **Choosing how hard to enforce a lesson.** The Stop hook's question, `/record` and the
+  guide now walk the same levels — briefing only, watched by CI (`--files` + `okl verify`),
+  build-breaking (a test or CI check), always-on (`CLAUDE.md`/`AGENTS.md`) — and the plugin
+  now ships the `encoding-loop` skill that holds the full table.
+- **`okl reverify`** re-runs the stored check of every drifted lesson after listing the
+  commands and getting a confirmation (or `--yes`).
+- **`okl verify` creates `okl-drift.json`** the first time a lesson that governs files is
+  verified, so there is no separate export step.
+- **The plugin's hooks step aside in repos never set up with `okl init`**; Decisions reach
+  the briefing; the service keeps `applies_to`; a getting-started guide
+  (docs/GETTING-STARTED.md); a docs audit's ~74 corrections; clean example re-runs.
+
 ## 0.7.2
 
 - **`okl record --verified` is refused.** It stamped a lesson verified with no evidence,

{observed_knowledge_ledger-0.7.2 → observed_knowledge_ledger-0.7.4}/CLAUDE.md

@@ -27,8 +27,7 @@ and editing `KNOWN_TAGS` changes the floor every store ships with.
   verification left uncommitted fails CI. Verifying before the code commit re-drifts.
   Give a rule `--files` only when CI does not already run its check (#39).
 - The local store (`.okl/okl.db`, gitignored) should hold all 11 seed files plus
-  recorded nodes; `okl seed seed/` loads the `*-defects.json` set, while
-  `dotnet-{canon,decisions,review-surfaces}.json` and `frontend-canon.json` load explicitly.
+  recorded nodes; `okl seed seed/` (or `okl seed --all`) loads all 11 packs.
 
 ## Commands
 
@@ -44,7 +43,8 @@ okl drift                          # rules whose governed source changed after v
 - **Mirror files are byte-identical, test-enforced**: `ci/okl-verify.yml` ==
   `.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
+  `gates/*.sh` == `src/okl/scaffold/gates/*.sh`; `.claude/hooks`, `.claude/commands/record.md`
+  and `.claude/skills/encoding-loop` mirror theirs too. 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
@@ -67,7 +67,7 @@ okl drift                          # rules whose governed source changed after v
 
 `src/okl/` is the package (store/core/client/cli/service/mcp + scaffold templates);
 `seed/` is the curated 161-node corpus (real lessons, real project names — deliberate);
-`evals/` is the A/B harness and receipts; `docs/posts/` is the 3-part write-up;
+`evals/` is the A/B harness and receipts; `docs/posts/` is the 4-part write-up;
 `e2e/` (gitignored) holds scratch repos for end-to-end loop tests.
 
 This file stays lean — always-on rules only. Everything conditionally relevant belongs

{observed_knowledge_ledger-0.7.2 → observed_knowledge_ledger-0.7.4}/CONTRIBUTING.md

@@ -17,7 +17,7 @@ Try it end to end in a scratch directory before changing anything:
 ```bash
 mkdir /tmp/try && cd /tmp/try && git init
 okl init --repo try --interests security
-okl seed
+okl seed dotnet-defects        # bare `okl seed` only lists the packs
 okl check --task "add an endpoint that returns an order for the logged-in user"
 ```
 
@@ -27,9 +27,15 @@ Read [CLAUDE.md](CLAUDE.md) (identical to AGENTS.md) before a first PR. It is sh
 it is the actual contract. The parts that will fail your build if you miss them:
 
 - **Mirror files are byte-identical.** `ci/okl-verify.yml`, `.github/workflows/okl-verify.yml`
-  and `src/okl/scaffold/ci/okl-verify.yml` must match, as must `hooks/*.sh` and their
-  `src/okl/scaffold/hooks/` twins. Edit one, copy to the others in the same change.
-  `tests/test_scaffold.py::test_mirror_files_identical` enforces it.
+  and `src/okl/scaffold/ci/okl-verify.yml` must match, as must `hooks/*.sh` and
+  `hooks/hooks.json` and their `src/okl/scaffold/hooks/` twins, `gates/*.sh` and their
+  `src/okl/scaffold/gates/` twins, and `CLAUDE.md` and `AGENTS.md`. Edit one, copy to the
+  others in the same change. `tests/test_scaffold.py::test_mirror_files_identical`
+  enforces it.
+- **CI runs more than the tests.** `ruff check .`, `mypy src/okl`, `pytest -q --cov=okl`
+  (the coverage floor is `fail_under` in `pyproject.toml`, currently 66%),
+  `./ci/check-diagram-figures.sh` and `bash gates/run-gates.sh` all gate the build; see
+  `.github/workflows/ci.yml`. Run them locally before pushing.
 - **The `okl-verify` check can fail on your PR, and that is not yours to fix.** CI reads
   the committed `okl-drift.json`: the rules that govern files, and when each was last
   verified. Change a governed file and CI names the rules that need re-checking. The
@@ -52,8 +58,10 @@ it is the actual contract. The parts that will fail your build if you miss them:
   commit keeps the branch's commits and their times; a squash or rebase creates new
   commits stamped at merge time, which makes every rule the PR touched look stale and
   turns `main` red. Do not re-enable them without changing how drift reads time.
-- **Tags come from a closed vocabulary** (`store.KNOWN_TAGS`). Growing it is a deliberate
-  edit to that set plus a note in the tags ADR, not an ad-hoc string.
+- **Tags come from a closed vocabulary** (`store.KNOWN_TAGS`), never an ad-hoc string.
+  A store can declare a tag for itself with
+  `okl record --type Vocabulary --scope org --title <tag>`. Editing `KNOWN_TAGS`, plus a
+  note in the tags ADR, is for a tag every store should ship with.
 - **Evaluation claims need a committed receipt.** If you change the harness or quote a
   number, the run that produced it belongs in `evals/results/`. Never cite a run the
   harness marked RESULTS NOT USABLE.
@@ -62,9 +70,9 @@ it is the actual contract. The parts that will fail your build if you miss them:
 
 - **Bug reports with a reproduction.** Especially anything where the tool reports success
   it did not earn; that class of defect is the project's whole subject.
-- **The open work in the store.** `okl check --task "improve retrieval precision"` will
-  show you the recorded defects against the tool itself, including the briefing relevance
-  cutoff that is still unfinished.
+- **The known gaps.** They are tracked as
+  [GitHub issues](https://github.com/emeraldleaf/okl/issues); the maintainer's store is
+  not in the repo (`.okl/` is gitignored), so a clone has no recorded defects to query.
 - **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