org-knowledge-layer 0.1.0__tar.gz

org_knowledge_layer-0.1.0/.claude/hooks/stop-okl-encode.sh

@@ -0,0 +1,78 @@
+#!/usr/bin/env bash
+# Stop hook — the write-side mechanical catch for the encoding loop.
+#
+# The read side (okl check) is enforced by the PreToolUse hook; nothing enforced the WRITE
+# side, so a session could end without recording what it learned ("a merged fix without the
+# rule is a half-finished job"). This hook asks the question at the ship moment, once:
+# if the session changed the working tree, block the first stop (exit 2) with a prompt to
+# either `okl record` the lesson or state that there is none. It never fires twice in one
+# session (marker file) and never loops (stop_hook_active guard).
+set -uo pipefail
+
+# Same resolver as pretooluse-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.
+resolve_okl() {
+  if [ -n "${OKL_BIN:-}" ]; then printf '%s' "$OKL_BIN"; return 0; fi
+  local d="$PWD"
+  while [ "$d" != "/" ]; do
+    if [ -f "$d/.okl/config.json" ]; then
+      local bin
+      bin=$(python3 -c 'import json,sys; print(json.load(open(sys.argv[1])).get("okl_bin") or "")' \
+            "$d/.okl/config.json" 2>/dev/null || true)
+      if [ -n "$bin" ]; then printf '%s' "$bin"; return 0; fi
+      break
+    fi
+    d=$(dirname "$d")
+  done
+  if command -v okl >/dev/null 2>&1; then printf '%s' "okl"; return 0; fi
+  if python3 -c "import okl" >/dev/null 2>&1; then printf '%s' "python3 -m okl"; return 0; fi
+  return 1
+}
+
+OKL=$(resolve_okl) || exit 0
+
+payload=$(cat 2>/dev/null || true)
+parsed=$(printf '%s' "$payload" | python3 -c '
+import json, sys
+try:
+    d = json.load(sys.stdin)
+except Exception:
+    d = {}
+print(d.get("session_id", ""))
+print("true" if d.get("stop_hook_active") else "false")
+' 2>/dev/null) || parsed=""
+session_id=$(printf '%s\n' "$parsed" | sed -n 1p)
+stop_hook_active=$(printf '%s\n' "$parsed" | sed -n 2p)
+[ -n "$stop_hook_active" ] || stop_hook_active="false"
+
+# Never loop: if we already blocked once and Claude is stopping again, let it stop.
+[ "${stop_hook_active}" = "true" ] && exit 0
+
+# Only fire when the session plausibly did work: uncommitted changes, or a commit in the
+# last hour (covers commit-then-stop sessions).
+changed=0
+if [ -n "$(git status --porcelain 2>/dev/null)" ]; then
+  changed=1
+elif last=$(git log -1 --format=%ct 2>/dev/null); then
+  now=$(date +%s)
+  [ $((now - last)) -lt 3600 ] && changed=1
+fi
+[ "$changed" = "1" ] || exit 0
+
+# Once per session (fall back to a repo-scoped marker when no session id is provided).
+marker="${TMPDIR:-/tmp}/okl-encode-reminder-${session_id:-$(pwd | cksum | cut -d' ' -f1)}"
+[ -e "$marker" ] && exit 0
+touch "$marker" 2>/dev/null || true
+
+cat >&2 <<'MSG'
+ENCODING LOOP — before this session ends: did it surface a lesson worth keeping?
+A non-obvious failure mode, a rule discovered the hard way, a decision that shouldn't be
+silently reversed? If yes, record it now (choose the scope deliberately — 'org' spreads
+to every repo, 'repo' stays local — and tag the subject):
+
+  okl record --type Defect|Rule|Decision --scope org|repo --tags "<subjects>" \
+    --title "..." --symptom "..." --body "cause: ..." --fix "..."
+
+If the session genuinely learned nothing durable, state that explicitly and finish.
+MSG
+exit 2

org_knowledge_layer-0.1.0/.claude/hooks/userpromptsubmit-okl-check.sh

@@ -0,0 +1,68 @@
+#!/usr/bin/env bash
+# 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
+# the briefing is retrieved for the task the user really asked for.
+#
+# (The earlier PreToolUse version fired on every edit and printed the briefing to a channel
+# the model never sees — PreToolUse exit-0 stdout goes to the transcript only. Discovered by
+# an end-to-end test: hook fired, briefing correct, defect reproduced anyway.)
+#
+# FAILS CLOSED via exit 2: if the knowledge layer is unreachable, the prompt is blocked
+# rather than letting the agent proceed blind. A check that reports "clean" while broken is
+# worse than no check.
+set -uo pipefail
+
+# 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.
+resolve_okl() {
+  if [ -n "${OKL_BIN:-}" ]; then printf '%s' "$OKL_BIN"; return 0; fi
+  local d="$PWD"
+  while [ "$d" != "/" ]; do
+    if [ -f "$d/.okl/config.json" ]; then
+      local bin
+      bin=$(python3 -c 'import json,sys; print(json.load(open(sys.argv[1])).get("okl_bin") or "")' \
+            "$d/.okl/config.json" 2>/dev/null || true)
+      if [ -n "$bin" ]; then printf '%s' "$bin"; return 0; fi
+      break
+    fi
+    d=$(dirname "$d")
+  done
+  if command -v okl >/dev/null 2>&1; then printf '%s' "okl"; return 0; fi
+  if python3 -c "import okl" >/dev/null 2>&1; then printf '%s' "python3 -m okl"; return 0; fi
+  return 1
+}
+
+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
+  exit 2
+fi
+
+# The task is the prompt itself (stdin JSON: {"prompt": "..."}); OKL_TASK overrides;
+# last-commit-message is only the fallback of last resort.
+payload=$(cat 2>/dev/null || true)
+prompt=$(printf '%s' "$payload" | python3 -c '
+import json, sys
+try:
+    print((json.load(sys.stdin).get("prompt") or "").strip()[:2000])
+except Exception:
+    print("")
+' 2>/dev/null || true)
+TASK="${OKL_TASK:-${prompt:-$(git log -1 --pretty=%s 2>/dev/null || echo 'general work')}}"
+
+# $OKL unquoted on purpose: it may be a command + args ("python3 -m okl").
+if out=$($OKL check --task "$TASK" --format agent 2>/dev/null); then
+  printf '%s\n' "$out"      # stdout → the model's context
+  exit 0
+fi
+
+if [ "${OKL_OFFLINE:-0}" = "1" ]; then
+  echo "OKL offline (OKL_OFFLINE=1 acknowledged) — proceeding without the layer." >&2
+  exit 0
+fi
+echo "OKL UNREACHABLE — blocking this prompt. A check that reports 'clean' while broken is worse than no check." >&2
+echo "Fix connectivity, or set OKL_OFFLINE=1 to explicitly proceed without the org knowledge layer." >&2
+exit 2

org_knowledge_layer-0.1.0/.claude/settings.json

@@ -0,0 +1,24 @@
+{
+  "hooks": {
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/stop-okl-encode.sh"
+          }
+        ]
+      }
+    ],
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/userpromptsubmit-okl-check.sh"
+          }
+        ]
+      }
+    ]
+  }
+}

org_knowledge_layer-0.1.0/.claude/settings.local.json

@@ -0,0 +1,79 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(chmod +x /Users/joshuadell/Dev/okl/src/okl/scaffold/hooks/stop-okl-encode.sh)",
+      "Bash(python3 -m pytest tests/test_scaffold.py::test_encode_hook_loop_guard_and_fires_once -q)",
+      "Bash(python3 -c ' *)",
+      "Bash(python3 -m okl --help)",
+      "Bash(python3 -c \"import psycopg; print\\('psycopg', psycopg.__version__\\)\")",
+      "Bash(sqlite3 -column /Users/joshuadell/Dev/okl/.okl/okl.db \"SELECT COUNT\\(*\\) as nodes FROM node; SELECT COUNT\\(*\\) as edges FROM edge;\")",
+      "Bash(sqlite3 -column /Users/joshuadell/Dev/okl/.okl/okl.db \"SELECT substr\\(id,1,40\\) as id, type, substr\\(title,1,50\\) as title FROM node WHERE id NOT LIKE 'seed:novacraft-defects%' AND id NOT LIKE 'seed:quartzose%' AND id NOT LIKE 'seed:san-juan%' AND id NOT LIKE 'seed:react%' ORDER BY created_at;\")",
+      "Bash(sqlite3 -column /Users/joshuadell/Dev/okl/.okl/okl.db \"SELECT substr\\(id,1,50\\) as id, substr\\(title,1,45\\) as title FROM node WHERE id LIKE 'seed:novacraft-defects%' OR id LIKE 'seed:quartzose%' OR id LIKE 'seed:san-juan%' OR id LIKE 'seed:react%' ORDER BY id;\")",
+      "Bash(sqlite3 /Users/joshuadell/Dev/okl/.okl/okl.db \"SELECT COUNT\\(*\\) FROM node WHERE id LIKE 'seed:%';\")",
+      "Bash(sqlite3 /Users/joshuadell/Dev/okl/.okl/okl.db \"SELECT datetime\\(created_at/1000,'unixepoch','localtime'\\) as t, COUNT\\(*\\) FROM node WHERE id LIKE 'seed:san-juan-en%' OR id LIKE 'seed:san-juan-ev%' GROUP BY t;\")",
+      "Bash(git init *)",
+      "Bash(timeout 60 claude -p --model haiku)",
+      "Bash(claude -p --model haiku)",
+      "Bash(python3 evals/ab_harness.py --dry-run)",
+      "Bash(GENERATOR_CMD=\"claude -p --model sonnet\" JUDGE_CMD=\"claude -p --model sonnet\" python3 evals/ab_harness.py --dry-run)",
+      "Bash(python3 evals/ab_harness.py --limit 2)",
+      "Bash(python3 evals/ab_harness.py)",
+      "Bash(python3 evals/ab_harness.py --dry-run --samples 3)",
+      "Bash(python3 evals/ab_harness.py --samples 3)",
+      "Bash(git add *)",
+      "Bash(git -c core.hooksPath=/dev/null commit -m 'okl v0: the sixth surface — cross-repo knowledge layer with enforced loop *)",
+      "Bash(okl drift *)",
+      "Bash(okl verify *)",
+      "Bash(echo \"drift exit=$?\")",
+      "Bash(git -c core.hooksPath=/dev/null commit -m 'A/B receipt: 3-sample run \\(48 runs, 0 failures\\) — baseline 33% defect reproduction, briefed 4% *)",
+      "Bash(GENERATOR_CMD=\"claude -p --model haiku\" JUDGE_CMD=\"claude -p --model sonnet\" python3 evals/ab_harness.py --samples 3)",
+      "Bash(git -c core.hooksPath=/dev/null commit -m 'A/B receipt: haiku generator \\(sonnet judge\\) — briefed haiku 12% vs unbriefed sonnet 33% *)",
+      "Bash(git -c core.hooksPath=/dev/null commit -m 'Evaluation report: full method, all four runs, findings, threats to validity *)",
+      "Bash(git -c core.hooksPath=/dev/null commit -m 'Report: add '\\\\''How to read these numbers'\\\\'' — plain-language meaning, verbatim judge verdicts *)",
+      "Bash(python3 -c \"import fastapi, uvicorn; print\\('fastapi', fastapi.__version__, '| uvicorn', uvicorn.__version__\\)\")",
+      "Bash(OKL_DATABASE_URL=\"sqlite:////Users/joshuadell/Dev/okl/.okl/okl.db\" okl serve --port 8765)",
+      "Bash(curl -sf http://localhost:8765/health)",
+      "Bash(curl -s http://localhost:8765/health)",
+      "Bash(okl connect *)",
+      "Bash(OKL_TASK=\"Add a GitHub Actions job step that lints the project with ruff and fails the build on findings\" claude -p \"Add a GitHub Actions workflow at .github/workflows/lint.yml with a job step that lints this Python project with ruff and fails the build on findings. Write the file, then stop.\" --permission-mode acceptEdits --allowedTools \"Write,Edit,Read\")",
+      "Bash(claude -p \"Add a GitHub Actions workflow at .github/workflows/lint.yml with a job step that lints this Python project with ruff and fails the build on findings. Write the file, then stop.\" --permission-mode acceptEdits --allowedTools \"Write,Edit,Read\")",
+      "Bash(okl record --type Rule --scope org --tags \"method\" \\\\ *)",
+      "Bash(git -c core.hooksPath=/dev/null commit -qm 'E2E finding: briefing delivery moved to UserPromptSubmit — PreToolUse stdout never reaches the model *)",
+      "Bash(git -c core.hooksPath=/dev/null commit -qm 'README: full honesty on the crowded space — not novel, why built anyway, compose with mem0/Zep *)",
+      "Bash(curl -s -o /dev/null -w \"%{http_code}\" https://pypi.org/pypi/okl/json)",
+      "Bash(sqlite3 .okl/okl.db \"SELECT COUNT\\(*\\) FROM node;\")",
+      "Bash(timeout_ok=1 uv run python render_excalidraw.py /Users/joshuadell/Dev/okl/docs/okl-sixth-surface.excalidraw --svg -o /Users/joshuadell/Dev/okl/docs/okl-sixth-surface.svg)",
+      "Bash(git -c core.hooksPath=/dev/null commit -qm 'P0 canon + mirror enforcement + store sync \\(handoff work-down\\) *)",
+      "Bash(git -c core.hooksPath=/dev/null commit -qm 'Re-export sixth-surface SVG — render now matches the .excalidraw source *)",
+      "Bash(ls -la \"/Users/joshuadell/Dev/emeraldleaf-dev/src/assets/\" 2>/dev/null | grep -i \"okl\\\\|surface\"; cp docs/okl-sixth-surface.svg \"/Users/joshuadell/Dev/emeraldleaf-dev/src/assets/okl-sixth-surface.svg\" 2>/dev/null && echo \"site asset synced\")",
+      "Bash(git -c core.hooksPath=/dev/null commit -qm 'Genericize project identities across the public surface *)",
+      "Bash(git branch *)",
+      "Bash(git -c core.hooksPath=/dev/null commit -qm 'okl v0.1 — the Org Knowledge Layer *)",
+      "Bash(git -c core.hooksPath=/dev/null commit -qm 'Close the migration leftovers: AGENTS.md, dead-hook purge, stale diagram *)",
+      "Bash(python3 -m pip install -q build twine)",
+      "Bash(python3 -m build)",
+      "Bash(python3 -m twine check dist/*)",
+      "Bash(unzip -l dist/*.whl)",
+      "Bash(git -C /Users/joshuadell/Dev/okl add docs/posts)",
+      "Bash(git -C /Users/joshuadell/Dev/okl -c core.hooksPath=/dev/null commit -qm 'Post 3: correct the read-hook mechanics; add the dead-channel lesson *)",
+      "Bash(git -C /Users/joshuadell/Dev/okl push -q origin main)",
+      "Bash(git -C /Users/joshuadell/Dev/okl log --oneline)",
+      "Bash(python3 -m twine --version)",
+      "Bash(python3 -c \"import setuptools; print\\('setuptools', setuptools.__version__\\)\")",
+      "Bash(python3 -c \"import hatchling; print\\('hatchling', hatchling.__version__ if hasattr\\(hatchling,'__version__'\\) else 'n/a'\\)\")",
+      "Bash(python3 -m pip list)",
+      "Bash(rm -rf oklbuild)",
+      "Bash(python3 -m venv oklbuild)",
+      "Bash(./oklbuild/bin/pip install *)",
+      "Bash(./oklbuild/bin/pip show *)",
+      "Bash(/tmp/oklbuild/bin/python -m build --no-isolation)",
+      "Bash(unzip -p dist/*.whl \"*/entry_points.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"
+    ]
+  }
+}

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

@@ -0,0 +1,22 @@
+# Repo CI — lints and tests okl itself. (okl-verify.yml is different: it demonstrates
+# the product's own drift/method gates, the workflow consumers copy into their repos.)
+name: ci
+on:
+  push:
+    branches: [ "main" ]
+  pull_request:
+    branches: [ "main" ]
+jobs:
+  lint-and-test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - uses: actions/setup-python@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: Tests
+        run: pytest -q

org_knowledge_layer-0.1.0/.github/workflows/okl-verify.yml

@@ -0,0 +1,59 @@
+# Installed by `okl init` into .github/workflows/okl-verify.yml (also stamped by `okl scaffold`).
+#
+# The knowledge layer's CI verifier — real checks, not placeholders:
+#   1. `okl drift --gate`  — fails the build when a rule's governed files changed after the
+#      rule was last verified (a stale rule is a rule nobody re-checked).
+#   2. `gates/run-gates.sh` — the repo's mechanical method gates, when the scaffold is present.
+#
+# Shared-layer connection is optional: without OKL_SERVICE_URL the drift gate runs against
+# the repo's local .okl store. Configure the secrets to verify against the org layer and to
+# let gate scripts emit receipts (`okl link <gate_id> VERIFIED_ON <defect_id>`) — emit those
+# from inside the gate that proved itself against real drift, where the ids are known.
+name: okl-verify
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+jobs:
+  okl-verify:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0   # drift needs history: it compares file mtimes/commits vs verified_at
+      - uses: actions/setup-python@v5
+        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).
+        run: |
+          if grep -q '^name = "okl"' pyproject.toml 2>/dev/null; then
+            pip install -e .
+          else
+            pip install okl
+          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 }}
+        run: |
+          if [ -n "${OKL_SERVICE_URL:-}" ]; then
+            okl connect "$OKL_SERVICE_URL" --token "$OKL_TOKEN"
+          else
+            echo "no OKL_SERVICE_URL secret — verifying against the repo-local store"
+          fi
+
+      - name: Drift gate — rules whose governed code changed after last verification
+        run: okl drift --gate
+
+      - name: Method gates (when the scaffold kit is present)
+        run: |
+          if [ -x gates/run-gates.sh ]; then
+            bash gates/run-gates.sh
+          else
+            echo "no gates/run-gates.sh — method-kit gates not installed (okl scaffold adds them)"
+          fi

org_knowledge_layer-0.1.0/.gitignore

@@ -0,0 +1,21 @@
+.DS_Store
+__pycache__/
+*.pyc
+*.egg-info/
+.okl/
+okl.db
+*.db
+.pytest_cache/
+dist/
+build/
+.venv/
+okl-starter-kit.tar.gz
+okl-bootstrap.json
+# scratch test repos created by smoke tests
+*_test/
+method-demo/
+e2e/
+
+
+#Ignore vscode AI rules
+.github/instructions/codacy.instructions.md

org_knowledge_layer-0.1.0/AGENTS.md

@@ -0,0 +1,62 @@
+# okl — repo instructions
+
+Read [evals/REPORT.md](evals/REPORT.md) before touching anything measurement-adjacent —
+it is the most load-bearing document in the repo (method, results, threats to validity).
+
+## The loop is LIVE in this repo
+
+The hooks fire on your own session: `UserPromptSubmit` injects the store's briefing into
+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.
+
+- **Verification is evidence-based**: `okl verify <id> --run "<check>" --expect "<signal>"`.
+  Never re-record with `--verified` to clear drift — run the check.
+- **After changing files a rule governs, `okl drift` goes red on purpose.** Re-verify
+  the affected nodes (their tests are usually the right `--run`) before finishing.
+- 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.
+
+## Commands
+
+```bash
+pytest -q                          # full suite; must be green before any commit
+ruff check .                       # lint (config in pyproject.toml)
+python3 evals/ab_harness.py --dry-run     # eval harness; see evals/README.md before running live
+okl drift                          # rules whose governed source changed after verification
+```
+
+## 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
+  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
+  compact setup style throughout; re-enabling it is a repo-wide style decision, not a
+  cleanup.
+- **Audits read the repo, not the working tree**: any gate/check that scans content
+  must scan `git ls-files` output (committed reality), never the dirty working tree —
+  scanning the tree makes an uncommitted edit pass or fail an audit that main would
+  answer differently. (Bit the .NET platform twice.)
+- **Eval integrity**: the harness refuses judge==generator; never quote a number from a
+  run marked RESULTS NOT USABLE; every cited figure needs a committed receipt in
+  `evals/results/`.
+- **The diagram and README move with the system**: they are drift-enrolled
+  (`n_b550ba9c5c8a`). `docs/okl-sixth-surface.svg` is a *render* of the `.excalidraw`
+  — if you edit the source, re-render or say loudly in the commit that the render is
+  stale.
+
+## Layout truth
+
+`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;
+`e2e/` (gitignored) holds scratch repos for end-to-end loop tests.
+
+This file stays lean — always-on rules only. Everything conditionally relevant belongs
+in the store, where the briefing selects it per task. If you're about to add a section
+here, ask whether it should be an `okl record` instead. It usually should.

org_knowledge_layer-0.1.0/CLAUDE.md

@@ -0,0 +1,62 @@
+# okl — repo instructions
+
+Read [evals/REPORT.md](evals/REPORT.md) before touching anything measurement-adjacent —
+it is the most load-bearing document in the repo (method, results, threats to validity).
+
+## The loop is LIVE in this repo
+
+The hooks fire on your own session: `UserPromptSubmit` injects the store's briefing into
+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.
+
+- **Verification is evidence-based**: `okl verify <id> --run "<check>" --expect "<signal>"`.
+  Never re-record with `--verified` to clear drift — run the check.
+- **After changing files a rule governs, `okl drift` goes red on purpose.** Re-verify
+  the affected nodes (their tests are usually the right `--run`) before finishing.
+- 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.
+
+## Commands
+
+```bash
+pytest -q                          # full suite; must be green before any commit
+ruff check .                       # lint (config in pyproject.toml)
+python3 evals/ab_harness.py --dry-run     # eval harness; see evals/README.md before running live
+okl drift                          # rules whose governed source changed after verification
+```
+
+## 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
+  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
+  compact setup style throughout; re-enabling it is a repo-wide style decision, not a
+  cleanup.
+- **Audits read the repo, not the working tree**: any gate/check that scans content
+  must scan `git ls-files` output (committed reality), never the dirty working tree —
+  scanning the tree makes an uncommitted edit pass or fail an audit that main would
+  answer differently. (Bit the .NET platform twice.)
+- **Eval integrity**: the harness refuses judge==generator; never quote a number from a
+  run marked RESULTS NOT USABLE; every cited figure needs a committed receipt in
+  `evals/results/`.
+- **The diagram and README move with the system**: they are drift-enrolled
+  (`n_b550ba9c5c8a`). `docs/okl-sixth-surface.svg` is a *render* of the `.excalidraw`
+  — if you edit the source, re-render or say loudly in the commit that the render is
+  stale.
+
+## Layout truth
+
+`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;
+`e2e/` (gitignored) holds scratch repos for end-to-end loop tests.
+
+This file stays lean — always-on rules only. Everything conditionally relevant belongs
+in the store, where the briefing selects it per task. If you're about to add a section
+here, ask whether it should be an `okl record` instead. It usually should.

org_knowledge_layer-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Joshua Dell
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.