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

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

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

{org_knowledge_layer-0.4.0 → org_knowledge_layer-0.5.0}/.github/workflows/ci.yml

@@ -78,6 +78,18 @@ jobs:
       # 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.
+      # The reviewer okl ships, run on okl. It was listed as a review surface with nothing
+      # triggering it — the "enforcement surface that only runs on-demand runs never"
+      # failure this repo's own store names. Off unless REVIEW_CMD is set, so it costs
+      # nothing until someone decides it should.
+      - name: Architecture review (off unless REVIEW_CMD is set)
+        if: github.event_name == 'pull_request'
+        env:
+          REVIEW_CMD: ${{ vars.REVIEW_CMD }}
+          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
+          REVIEW_BASE_REF: origin/${{ github.base_ref }}
+        run: bash ci/review-agent.sh
+
       - name: Secret scan — gitleaks
         env:
           GITLEAKS_VERSION: "8.30.1"

{org_knowledge_layer-0.4.0/ci → org_knowledge_layer-0.5.0/.github/workflows}/okl-verify.yml

@@ -16,16 +16,45 @@ on:
   push:
     branches: [main]
 
+# Least privilege: this workflow reads code and reports a status. It never writes.
+permissions:
+  contents: read
+
+concurrency:
+  group: okl-verify-${{ 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:
   okl-verify:
     runs-on: ubuntu-latest
+    env:
+      # Set at job level so every okl command below resolves the shared layer from the
+      # environment. This replaces an `okl connect --token` step, which wrote the bearer
+      # token into .okl/config.json on the runner — needless, since the client reads both
+      # variables directly, and one more place for a credential to end up.
+      # Unset secrets leave these empty, and okl falls back to the repo-local store.
+      OKL_SERVICE_URL: ${{ secrets.OKL_SERVICE_URL }}
+      OKL_TOKEN: ${{ secrets.OKL_TOKEN }}
     steps:
-      - uses: actions/checkout@v4
+      # Actions are pinned to a commit SHA: a tag is mutable, so `@v5` is an unpinned
+      # dependency with access to your runner. If you copy this file into your own repo,
+      # add a .github/dependabot.yml with the `github-actions` ecosystem so these pins get
+      # security updates — a pin with no update path goes stale and that is its own risk.
+      - uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09  # v5
         with:
-          fetch-depth: 0   # drift needs history: it compares file mtimes/commits vs verified_at
-      - uses: actions/setup-python@v5
+          fetch-depth: 0   # drift needs history: it compares governed-file commits vs verified_at
+          persist-credentials: false   # this job never pushes
+
+      - uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1  # v6
         with:
           python-version: "3.13"
+
       - name: Install okl
         # 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.
@@ -36,13 +65,10 @@ jobs:
             pip install org-knowledge-layer
           fi
 
-      - name: Connect to the shared layer (optional — skipped when secrets are unset)
-        env:
-          OKL_SERVICE_URL: ${{ secrets.OKL_SERVICE_URL }}
-          OKL_TOKEN: ${{ secrets.OKL_TOKEN }}
+      - name: Report which store the gate will run against
         run: |
           if [ -n "${OKL_SERVICE_URL:-}" ]; then
-            okl connect "$OKL_SERVICE_URL" --token "$OKL_TOKEN"
+            echo "verifying against the shared layer at $OKL_SERVICE_URL"
           else
             echo "no OKL_SERVICE_URL secret — verifying against the repo-local store"
           fi

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

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

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

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

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

@@ -1,5 +1,68 @@
 # Changelog
 
+## 0.5.0
+
+### The vocabulary is no longer fixed in the package
+
+- **A store can declare its own subject tags.** `KNOWN_TAGS` remains, but as the *floor*
+  every store ships with rather than the whole vocabulary. Widen it by recording a
+  `Vocabulary` node, whose title is the tag:
+
+  ```bash
+  okl record --type Vocabulary --scope org --title rust --body "Rust services."
+  okl record --type Rule --scope org --tags rust --title "Prefer ? over unwrap in handlers"
+  ```
+
+  Before this, a Go, Rust or PowerShell team could not file a lesson under its own language
+  without forking the package, which is a hard stop on adoption for a tool whose claim is
+  that a lesson learned in one place reaches another. What the closed vocabulary was *for*
+  survives: it catches the typo that files a record where nobody looks, and closed-per-store
+  still does, so `rustt` is refused in a store that declared `rust`. What changes is who may
+  grow it. `STACK_TAGS`, which gates `applies_to`, is deliberately not extended.
+
+- **`frontend` and `prose` added to the floor.** Neither is specific to one org: any repo
+  that renders markup has frontend lessons, and any repo that governs its writing has prose
+  ones. `react` was the nearest existing tag for the first and is wrong, being a stack tag.
+
+### Fixed
+
+- **The hooks no longer tell you to run `pip install okl`, which cannot work.** PyPI refuses
+  `okl` as confusable, so the distribution is `org-knowledge-layer` and `okl` is only the
+  console script. The wrong name was in the `UserPromptSubmit` hook's not-found message,
+  which fires *exactly* when someone has no working install and sent them to a 404 that
+  reads as "this tool was never published." `okl init` stamps that hook into every repo it
+  touches, so the error propagated with adoption. Re-run `okl init` to pick up the new file.
+- `cli.py`'s MCP hint said `pip install okl[mcp]`; now `pip install 'org-knowledge-layer[mcp]'`,
+  quoted because zsh globs unquoted brackets.
+
+
+## 0.4.1
+
+### Security — affects the CI workflow already in your repo
+
+- **The shipped CI verifier no longer writes your bearer token to disk.** It ran
+  `okl connect --token`, which persisted `OKL_TOKEN` into `.okl/config.json` on the runner
+  for no reason: the client reads `OKL_SERVICE_URL` and `OKL_TOKEN` from the environment
+  directly, so setting them at job level does the same work with the credential never
+  touching the filesystem. Re-run `okl init` (or `okl scaffold`) to pick up the new file.
+- **Both shipped workflows are hardened.** `okl-verify.yml` and `method-gates.yml` now
+  declare least-privilege `permissions`, a concurrency group, `pipefail`, and
+  `persist-credentials: false`, and pin their actions to commit SHAs rather than mutable
+  tags. They satisfied none of that before.
+- `.github/dependabot.yml` ships with the kit, because pinning to a SHA without an update
+  path is how a repo ends up on a two-year-old action and calls it hardening.
+
+### Added
+
+- **Opt-in architecture review in CI.** `ci/review-agent.sh` runs the reviewer over a PR
+  diff and fails on must-fix findings. **Off unless you set the `REVIEW_CMD` repository
+  variable** to a CLI that reads a prompt on stdin — `claude -p` (authenticates with an
+  existing Claude Code login, no separate API key), `ollama run <model>` (local, free), or
+  any other. Unset, it prints one line and passes. It is the only gate in the kit that
+  calls a model, which is why it is the only one that is opt-in. Documented in the README
+  and the kit manifest.
+
+
 ## 0.4.0
 
 ### Behaviour changes worth reading before upgrading

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

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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: org-knowledge-layer
-Version: 0.4.0
+Version: 0.5.0
 Summary: Org Knowledge Layer — an installable sixth surface that carries encoded engineering lessons across repos.
 Author: Joshua Dell
 License: MIT
@@ -19,7 +19,7 @@ Requires-Dist: httpx>=0.27; extra == 'dev'
 Requires-Dist: mypy==2.3.1; extra == 'dev'
 Requires-Dist: pydantic>=2; extra == 'dev'
 Requires-Dist: pytest-cov==7.1.0; extra == 'dev'
-Requires-Dist: pytest==8.4.2; extra == 'dev'
+Requires-Dist: pytest==9.1.1; extra == 'dev'
 Requires-Dist: ruff==0.16.5; extra == 'dev'
 Requires-Dist: uvicorn>=0.29; extra == 'dev'
 Provides-Extra: mcp
@@ -210,6 +210,20 @@ with receipts, not a benchmark.
 
 <img src="docs/okl-how-it-works.svg" alt="One repo records a lesson; every other repo is briefed on it before its next task. The store is typed, scoped and tagged; every verification stamp carries the check that earned it." width="100%">
 
+### How a briefing is actually built
+
+`okl check` is a retrieval pipeline: seven stages turn a task sentence and the whole corpus
+into the twelve records an agent reads. Two stages can drop a record, and only one of them
+is entitled to — the distinction that this project got wrong once and measured its way out
+of ([REPORT §4d](evals/REPORT.md)).
+
+<img src="docs/okl-retrieval-pipeline.svg" alt="Seven stages: the corpus, a BM25 fetch of three times the limit, a scope gate, the exclusive applies_to filter, the inclusive tags-times-interests filter, a top-12 cutoff, bucketing by type, and rendering. Each stage shows how many records survive it." width="100%">
+
+Every count in that diagram is **traced**, not transcribed — `docs/render_pipeline_diagram.py`
+runs the real `store.search` and `core._in_scope` against a store seeded from `seed/`, and
+`test_pipeline_diagram_is_current` fails if the committed render is not what the generator
+produces today. Change a BM25 weight or a filter predicate and the diagram goes red with it.
+
 ### The mental model
 
 `okl` stores small, typed **notes** and the **links** between them.
@@ -358,6 +372,32 @@ To remove okl from a repo entirely, delete `.okl/`, the two hook scripts and the
 in `.claude/settings.json`, and `.github/workflows/okl-verify.yml`. Nothing else was
 written, and nothing outside that repo was touched.
 
+### Architecture review in CI (off by default)
+
+The kit ships a reviewer that reads a PR diff against your encoded rules and fails the
+build on a must-fix finding. It is **off unless you ask for it**, and it is not tied to any
+vendor. Set the `REVIEW_CMD` repository variable to any CLI that reads a prompt on stdin:
+
+```bash
+gh variable set REVIEW_CMD --body "claude -p --model sonnet"   # your existing Claude Code login
+gh variable set REVIEW_CMD --body "ollama run qwen2.5-coder"   # local model, no API cost
+gh variable set REVIEW_CMD --body "llm -m gpt-4o"              # any other CLI
+```
+
+Two things worth knowing:
+
+- **`claude -p` needs no separate API key.** It authenticates with the Claude Code login you
+  already have, so if you use Claude Code there is nothing else to configure and no second
+  bill. Verified headless with `ANTHROPIC_API_KEY` unset.
+- **Locally you do not need this at all.** The reviewer is a subagent
+  (`.claude/agents/architecture-reviewer.md`); ask your agent to run it on your changes and
+  it costs nothing beyond the session you are already in. The CI job exists for the case
+  where no human and no agent is in the loop — a PR nobody reviewed.
+
+Unset, the step prints one line saying it is off and exits 0. Every other gate in the kit is
+deterministic and free; this is the only one that calls a model, which is why it is the only
+one that is opt-in.
+
 ## Wire a repo
 
 ```bash

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

@@ -176,6 +176,20 @@ with receipts, not a benchmark.
 
 <img src="docs/okl-how-it-works.svg" alt="One repo records a lesson; every other repo is briefed on it before its next task. The store is typed, scoped and tagged; every verification stamp carries the check that earned it." width="100%">
 
+### How a briefing is actually built
+
+`okl check` is a retrieval pipeline: seven stages turn a task sentence and the whole corpus
+into the twelve records an agent reads. Two stages can drop a record, and only one of them
+is entitled to — the distinction that this project got wrong once and measured its way out
+of ([REPORT §4d](evals/REPORT.md)).
+
+<img src="docs/okl-retrieval-pipeline.svg" alt="Seven stages: the corpus, a BM25 fetch of three times the limit, a scope gate, the exclusive applies_to filter, the inclusive tags-times-interests filter, a top-12 cutoff, bucketing by type, and rendering. Each stage shows how many records survive it." width="100%">
+
+Every count in that diagram is **traced**, not transcribed — `docs/render_pipeline_diagram.py`
+runs the real `store.search` and `core._in_scope` against a store seeded from `seed/`, and
+`test_pipeline_diagram_is_current` fails if the committed render is not what the generator
+produces today. Change a BM25 weight or a filter predicate and the diagram goes red with it.
+
 ### The mental model
 
 `okl` stores small, typed **notes** and the **links** between them.
@@ -324,6 +338,32 @@ To remove okl from a repo entirely, delete `.okl/`, the two hook scripts and the
 in `.claude/settings.json`, and `.github/workflows/okl-verify.yml`. Nothing else was
 written, and nothing outside that repo was touched.
 
+### Architecture review in CI (off by default)
+
+The kit ships a reviewer that reads a PR diff against your encoded rules and fails the
+build on a must-fix finding. It is **off unless you ask for it**, and it is not tied to any
+vendor. Set the `REVIEW_CMD` repository variable to any CLI that reads a prompt on stdin:
+
+```bash
+gh variable set REVIEW_CMD --body "claude -p --model sonnet"   # your existing Claude Code login
+gh variable set REVIEW_CMD --body "ollama run qwen2.5-coder"   # local model, no API cost
+gh variable set REVIEW_CMD --body "llm -m gpt-4o"              # any other CLI
+```
+
+Two things worth knowing:
+
+- **`claude -p` needs no separate API key.** It authenticates with the Claude Code login you
+  already have, so if you use Claude Code there is nothing else to configure and no second
+  bill. Verified headless with `ANTHROPIC_API_KEY` unset.
+- **Locally you do not need this at all.** The reviewer is a subagent
+  (`.claude/agents/architecture-reviewer.md`); ask your agent to run it on your changes and
+  it costs nothing beyond the session you are already in. The CI job exists for the case
+  where no human and no agent is in the loop — a PR nobody reviewed.
+
+Unset, the step prints one line saying it is off and exits 0. Every other gate in the kit is
+deterministic and free; this is the only one that calls a model, which is why it is the only
+one that is opt-in.
+
 ## Wire a repo
 
 ```bash

{org_knowledge_layer-0.4.0/src/okl/scaffold → org_knowledge_layer-0.5.0}/ci/okl-verify.yml

@@ -16,16 +16,45 @@ on:
   push:
     branches: [main]
 
+# Least privilege: this workflow reads code and reports a status. It never writes.
+permissions:
+  contents: read
+
+concurrency:
+  group: okl-verify-${{ 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:
   okl-verify:
     runs-on: ubuntu-latest
+    env:
+      # Set at job level so every okl command below resolves the shared layer from the
+      # environment. This replaces an `okl connect --token` step, which wrote the bearer
+      # token into .okl/config.json on the runner — needless, since the client reads both
+      # variables directly, and one more place for a credential to end up.
+      # Unset secrets leave these empty, and okl falls back to the repo-local store.
+      OKL_SERVICE_URL: ${{ secrets.OKL_SERVICE_URL }}
+      OKL_TOKEN: ${{ secrets.OKL_TOKEN }}
     steps:
-      - uses: actions/checkout@v4
+      # Actions are pinned to a commit SHA: a tag is mutable, so `@v5` is an unpinned
+      # dependency with access to your runner. If you copy this file into your own repo,
+      # add a .github/dependabot.yml with the `github-actions` ecosystem so these pins get
+      # security updates — a pin with no update path goes stale and that is its own risk.
+      - uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09  # v5
         with:
-          fetch-depth: 0   # drift needs history: it compares file mtimes/commits vs verified_at
-      - uses: actions/setup-python@v5
+          fetch-depth: 0   # drift needs history: it compares governed-file commits vs verified_at
+          persist-credentials: false   # this job never pushes
+
+      - uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1  # v6
         with:
           python-version: "3.13"
+
       - name: Install okl
         # 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.
@@ -36,13 +65,10 @@ jobs:
             pip install org-knowledge-layer
           fi
 
-      - name: Connect to the shared layer (optional — skipped when secrets are unset)
-        env:
-          OKL_SERVICE_URL: ${{ secrets.OKL_SERVICE_URL }}
-          OKL_TOKEN: ${{ secrets.OKL_TOKEN }}
+      - name: Report which store the gate will run against
         run: |
           if [ -n "${OKL_SERVICE_URL:-}" ]; then
-            okl connect "$OKL_SERVICE_URL" --token "$OKL_TOKEN"
+            echo "verifying against the shared layer at $OKL_SERVICE_URL"
           else
             echo "no OKL_SERVICE_URL secret — verifying against the repo-local store"
           fi

org_knowledge_layer-0.5.0/ci/review-agent.sh

@@ -0,0 +1,133 @@
+#!/usr/bin/env bash
+# review-agent.sh — run the architecture reviewer over a PR diff, headless.
+#
+# Closes the gap the store names as "an enforcement surface that only runs on-demand runs
+# never": .claude/agents/architecture-reviewer.md is listed as a review surface but nothing
+# triggers it, so in practice it runs when someone remembers, which is never.
+#
+# OFF BY DEFAULT, AND VENDOR-NEUTRAL. Set REVIEW_CMD to any CLI that reads a prompt on
+# stdin and writes the model's reply to stdout:
+#
+#   REVIEW_CMD="claude -p --model sonnet"
+#   REVIEW_CMD="llm -m gpt-4o"
+#   REVIEW_CMD="ollama run qwen2.5-coder"        # local, no API cost at all
+#
+# Unset, the step soft-passes and says how to switch it on. okl is harness-agnostic —
+# hard-coding one vendor's CLI here would contradict that, and would hand every consumer
+# an API bill they never asked for. This mirrors GENERATOR_CMD/JUDGE_CMD in evals/.
+#
+# Self-owned on purpose: no third-party review SaaS holds a token for your source, and the
+# reviewer reads YOUR encoded rules (it calls `okl check` itself) rather than generic advice.
+set -uo pipefail
+cd "$(dirname "$0")/.."
+
+# Located, not assumed: `okl scaffold --claude-dir` lets a repo name that directory
+# something other than .claude, and a hard-coded path silently skips the review in exactly
+# those repos — a gate that quietly does nothing is the failure this whole file exists to
+# fix. AGENT_FILE overrides for anything unusual.
+AGENT="${AGENT_FILE:-}"
+if [ -z "$AGENT" ]; then
+  AGENT="$(find . -maxdepth 3 -path ./.git -prune -o \
+           -name architecture-reviewer.md -print 2>/dev/null | head -1)"
+fi
+BASE="${REVIEW_BASE_REF:-origin/main}"
+
+if [ -z "${REVIEW_CMD:-}" ]; then
+  echo "review-agent: REVIEW_CMD not set — skipping (soft pass)."
+  echo "  Set it to any CLI that takes a prompt on stdin to turn this into a blocking gate,"
+  echo "  e.g. REVIEW_CMD=\"claude -p --model sonnet\" or REVIEW_CMD=\"ollama run qwen2.5-coder\"."
+  exit 0
+fi
+if [ ! -f "$AGENT" ]; then
+  echo "review-agent: no $AGENT — skipping (the reviewer ships with \`okl scaffold\`)."
+  exit 0
+fi
+# shellcheck disable=SC2086 — REVIEW_CMD is a command line, so word splitting is intended
+if ! command -v ${REVIEW_CMD%% *} >/dev/null 2>&1; then
+  echo "review-agent: '${REVIEW_CMD%% *}' from REVIEW_CMD is not on PATH — skipping (soft pass)." >&2
+  exit 0
+fi
+
+diff_text="$(git diff "$BASE"...HEAD 2>/dev/null)"
+if [ -z "$diff_text" ]; then
+  echo "review-agent: no diff against $BASE — nothing to review."
+  exit 0
+fi
+
+# Truncate: a very large diff would blow the context budget and produce a worse review than
+# a focused one. Reviewing the first N lines and saying so beats silently reviewing a
+# truncated diff as though it were whole.
+max_lines=4000
+total_lines=$(printf '%s' "$diff_text" | wc -l | tr -d ' ')
+if [ "$total_lines" -gt "$max_lines" ]; then
+  diff_text="$(printf '%s' "$diff_text" | head -n "$max_lines")"
+  echo "review-agent: diff is $total_lines lines; reviewing the first $max_lines."
+fi
+
+# The checklist lives in the agent file — one source of truth for the rules. Only the OUTPUT
+# CONTRACT is supplied here, because the agent is written for interactive use and returns
+# prose, which CI cannot act on.
+prompt="$(cat <<EOF
+You are the architecture reviewer defined below. Apply its checklist to the diff.
+
+$(cat "$AGENT")
+
+--- DIFF UNDER REVIEW ---
+$diff_text
+--- END DIFF ---
+
+Reply with STRICT JSON and nothing else:
+{"findings":[{"severity":"must-fix|consider","file":"path","line":0,"rule":"which checklist item","finding":"one sentence"}]}
+
+Rules for your reply:
+- "must-fix" is reserved for a violation of an encoded rule: a restated retraction, a
+  resurrected tombstoned identifier, a speculative abstraction, an assert-from-memory claim.
+  Style preferences and suggestions are "consider".
+- Only report what this diff introduces. Pre-existing issues are out of scope.
+- An empty findings list is a valid and common answer. Do not invent findings to seem useful.
+EOF
+)"
+
+echo "review-agent: reviewing $(printf '%s' "$diff_text" | wc -l | tr -d ' ') lines of diff against $BASE"
+# CLEAN ROOM. Run the reviewer from a temp directory, never the repo. If REVIEW_CMD is a
+# coding agent, this repo's own hooks would otherwise fire on it: the UserPromptSubmit hook
+# injects a briefing into the review, and the Stop hook answers instead of the reviewer.
+# Reproduced while verifying this script — a smoke call in the repo cwd came back answering
+# the Stop hook rather than the question, which is the same failure evals/ documents.
+clean="$(mktemp -d)"
+raw="$(cd "$clean" && printf '%s' "$prompt" | $REVIEW_CMD 2>/dev/null)"
+rmdir "$clean" 2>/dev/null || true
+
+# Strip any markdown fence the model adds around the JSON.
+json="$(printf '%s' "$raw" | sed -e 's/^```json//' -e 's/^```//' -e '/^```$/d')"
+
+if ! printf '%s' "$json" | python3 -c "import json,sys; json.load(sys.stdin)" 2>/dev/null; then
+  # Fail OPEN on an unparseable reply, loudly. A reviewer that cannot be understood has not
+  # found anything; blocking every merge on a malformed model response would train people to
+  # bypass the gate, which is worse than the gate not firing.
+  echo "review-agent: could not parse the reviewer's reply as JSON — not blocking." >&2
+  printf '%s\n' "$raw" | head -20 >&2
+  exit 0
+fi
+
+printf '%s' "$json" | python3 -c '
+import json, sys
+
+# %-formatting rather than f-strings: this is embedded in a shell single-quoted string, so
+# the keys need double quotes, and a backslash inside an f-string EXPRESSION is a SyntaxError
+# before Python 3.12 — which this must survive, since it runs on whatever interpreter the
+# consumer has. The first version hit exactly that and exited 1 on every run. A gate that
+# always blocks looks identical to a gate that works until someone notices nothing has ever
+# passed it.
+findings = json.load(sys.stdin).get("findings", [])
+must = [f for f in findings if f.get("severity") == "must-fix"]
+for f in findings:
+    mark = "MUST-FIX" if f.get("severity") == "must-fix" else "consider"
+    print("  [%s] %s:%s  %s" % (mark, f.get("file"), f.get("line"), f.get("rule")))
+    print("            %s" % f.get("finding"))
+if not findings:
+    print("  no findings")
+print()
+print("review-agent: %d must-fix, %d to consider" % (len(must), len(findings) - len(must)))
+sys.exit(1 if must else 0)
+'

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

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