org-knowledge-layer 0.1.0__py3-none-any.whl

okl/scaffold/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

okl/scaffold/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

okl/scaffold/plugin/plugin.json

@@ -0,0 +1,10 @@
+{
+  "name": "encoding-loop-method",
+  "version": "0.1.0",
+  "description": "The encoding-loop engineering method as an installable Claude Code plugin: lean canon, the encoding-loop skill, an architecture-reviewer subagent, feature-spec and check-rules commands, a fail-closed pre-task hook wired to the okl org knowledge layer, and portable drift-gates + an eval tier.",
+  "author": "Joshua Dell",
+  "skills": ["./skills/encoding-loop"],
+  "agents": ["./agents/architecture-reviewer.md"],
+  "commands": ["./commands/feature-spec.md", "./commands/check-rules.md"],
+  "hooks": "./hooks/hooks.json"
+}

okl/scaffold/profiles/dotnet/README.md

@@ -0,0 +1,12 @@
+# .NET microservices profile
+
+Canon extracted verbatim from the .NET platform (`.NET 10 / Aspire / RabbitMQ-Wolverine / gRPC / EF Core`).
+Installed to `.claude/rules/` as path-scoped rule files (load only when matching files are in context):
+
+- `architecture.md` — VSA + DDD + CQRS; consumer-substitution interface rule; VSA→Clean promotion signal
+- `security.md` — IDOR→404, JWT ClockSkew, server-controlled fields, rate-limiter scale-out
+- `performance-and-data.md` — DbContext-direct (no repository wrappers), EF projection, async, Guid v7
+- `messaging.md` — Wolverine/RabbitMQ topology, outbox atomicity, handler-discovery≠DI, gRPC/REST versioning
+
+Has a React frontend? The React canon is a **separate, backend-agnostic profile** — stack it on:
+`okl scaffold --profile dotnet --profile react`.

okl/scaffold/profiles/dotnet/rules/architecture.md

@@ -0,0 +1,55 @@
+---
+description: SOLID / DDD / VSA architecture rules for .NET microservices
+paths: ["**/*.cs"]
+---
+
+# Architecture (.NET microservices — VSA + DDD + CQRS)
+
+> Ported verbatim from the .NET platform CLAUDE.md. Stack: .NET 10, Aspire, RabbitMQ (Wolverine),
+> gRPC, EF Core, React. DDD + CQRS + event-driven.
+
+## Vertical Slice Architecture is the default for every service
+
+- Organize by **feature**, not by kind. `ServiceName/Features/` holds one file per use case:
+  command/query record + validator + handler co-located. Saga event-handlers live here too.
+- `Domain/` holds only what is *genuinely shared* across features — aggregates, value objects, enums,
+  and consumer-substitution ports. `Infrastructure/` holds EF Core, caching, gateways, DI. `Program.cs`
+  is the composition root.
+- **Feature-file soft cap ~300 lines.** Past it, extract the validator or line-item record into a
+  sibling file in `Features/` — the cap is on size, not file-count-per-slice.
+- **Don't apply both VSA and Clean across one service.** Pick one shape per service and commit. The
+  cross-service pattern diff is intentional — it's the project's lesson, not an inconsistency.
+
+## Promotion signal — when to consider Clean Architecture
+
+- VSA stays the default. Consider a multi-project split ONLY at 5+ aggregates per service with
+  cross-cutting domain rules several features coordinate on, AND `Domain/` growing faster than `Features/`.
+- The **dependency rule** (Domain → nothing; IO at the edges) is already in force in VSA at every scale —
+  it is not complexity-gated. Only the multi-project *structure* is gated.
+- Escalate enforcement as the cost of a violated boundary rises: **convention → architecture tests
+  (NetArchTest/analyzer) → project split.** The middle rung enforces the same boundary the 4-project
+  split does, deterministically, without the project ceremony. Reach for the split only when you want
+  the *compiler* (not a test) to hold the line, or need separate deploy/versioning units.
+
+## SOLID (the load-bearing parts)
+
+- Domain → nothing. Application → Domain. Infrastructure → Domain + Application. Api → all (composition root).
+- A service with no domain entities doesn't need a Domain project — ports (`I*Sender`, `I*Resolver`)
+  live in `Application/Interfaces/`.
+- **Interfaces earn their keep through consumer substitution, not "future swap."** A port/adapter
+  interface is justified only if **(a)** it's substituted by tests today (`grep "Substitute.For<IFoo"`),
+  **(b)** 2+ concrete impls are registered today, or **(c)** a second impl is on a *concrete* near-term
+  roadmap. If none hold, it's speculative coupling — delete it, take the concrete class.
+- **Factory / `[FromKeyedServices]` is the shape ONCE condition (b) holds — not before.** A factory
+  that returns the same single impl for every input is the same speculative coupling as a deleted
+  `I*Repository`. Introduce it the day the second impl actually ships.
+
+## DDD
+
+- **Rich domain entities only when someone observes the invariant.** Persisted entity with non-trivial
+  observable invariants → state changes go through methods, never public setters, with validating
+  `static Create()` factories. In-memory, single-use, discarded-after-handler → skip the aggregate shape,
+  inline the validation or use a FluentValidation rule.
+- Value objects for Money (amount+currency), Quantity (non-negative). Aggregates control their children —
+  no mutable collection exposure (`IReadOnlyList<T>` over `private readonly List<T>`; add via `AddLine()`).
+- Domain events for state changes that affect other bounded contexts.

okl/scaffold/profiles/dotnet/rules/messaging.md

@@ -0,0 +1,31 @@
+---
+description: Wolverine / RabbitMQ messaging, outbox, gRPC, versioning rules
+paths: ["**/Program.cs", "**/Features/**/*.cs", "**/*RecoveryJob*.cs"]
+---
+
+# Communication patterns (.NET — Wolverine / RabbitMQ / gRPC)
+
+> Ported verbatim from the .NET platform CLAUDE.md. Each bullet is a dated distributed-systems trap.
+
+## Transport & topology
+
+- **Messaging transport is RabbitMQ** in every environment (dev matches prod). Wolverine maps saga pub/sub onto fanout exchanges (one per event family) with a queue per consumer. **Azure Service Bus was evaluated and removed** — its local emulator can't run the saga; re-add only if Azure becomes a real target.
+- **Fanout exchanges silently DISCARD unroutable messages; AutoProvision declares topology lazily per service.** An event published before a consumer's first boot is dropped while the outbox marks it delivered. Rule: **each publisher declares its own exchange AND its consumers' queues+bindings** (`BindExchange(...).ToQueue(...)`), names from `MessagingExchanges`/`MessagingQueues` constants — never inline literals (a typo'd name is auto-provisioned as an empty object and the consumer starves silently).
+- **Wolverine durability is per-direction.** `UseDurableOutboxOnAllSendingEndpoints()` covers ONLY the send side; default listeners are buffered (acked before handlers run — a crash loses the buffer). Store-backed services call `UseDurableInboxOnAllListeners()`; store-less services use `.ProcessInline()`. Every new `ListenToRabbitQueue` gets one of the two.
+- **Durability ≠ replay.** Durable pub/sub (RabbitMQ durable queues + transactional outbox + idempotent handlers) does NOT lose messages. Reach for a stream (Kafka/Event Hubs/Redis Streams) only when you need replay-from-offset, multi-day retention, an ordered append-only log, or N independent re-reading consumers — not merely "don't lose messages."
+
+## Outbox atomicity
+
+- **Transactional publishing must use the enlisted context, NOT constructor-injected `IEventPublisher`.** Only the `IMessageContext` Wolverine injects as a `HandleAsync` parameter (or an `IDbContextOutbox` in non-handler code) is enlisted in the outbox transaction. A constructor-injected `IMessageBus`/`IEventPublisher` publishes inline under Wolverine 6 — before commit — breaking outbox atomicity.
+- **Outbox outside a handler:** `BeginTransactionAsync` → entity write + `PublishAsync` → **`SaveChangesAsync`** → `CommitAsync`. Skipping the `SaveChangesAsync` between publish and commit silently drops the staged envelope.
+
+## Handler discovery, gRPC, REST versioning
+
+- **Wolverine handler discovery is NOT DI registration — two separate containers.** `opts.Discovery.IncludeAssembly(...)` builds Wolverine's internal message→handler map; Wolverine constructs handlers itself. `serviceProvider.GetRequiredService<MyHandler>()` throws unless you also `AddScoped<MyHandler>()`. The path that hits this is integration tests resolving handlers directly — every such handler needs an explicit `AddScoped<T>()`.
+- **No `IRequestHandler`/`IFooHandler` interface per handler.** Handlers are plain classes; Wolverine's bus is the abstraction. Handler interfaces fail the consumer-substitution test the same way `IFooRepository` did.
+- **gRPC** (sync) for real-time inter-service queries, versioned via `.proto` `package`. **REST** (HTTP) for frontend only, URL-segment versioned — always `app.MapV1ApiGroup("Tag", "resource")`, never hand-rolled `NewVersionedApi(...).MapGroup(...).HasApiVersion(...)` chains.
+
+## Package management (Aspire)
+
+- Central Package Management via `Directory.Packages.props`; `.csproj` references packages without versions.
+- **Aspire SDK and runtime packages must match** (minor included) — bump together. **Aspire 13+ Azure resources need explicit local-dev fallbacks** (gate on `IsPublishMode`). **`WithReference(x)` ≠ wait-for-healthy** — every `WithReference` on a non-trivial dependency gets a matching `.WaitFor(x)`.

okl/scaffold/profiles/dotnet/rules/performance-and-data.md

@@ -0,0 +1,36 @@
+---
+description: EF Core, async, concurrency, pagination performance rules
+paths: ["**/Features/**/*.cs", "**/Infrastructure/**/*.cs", "**/Domain/**/*.cs"]
+---
+
+# Performance & data correctness (.NET / EF Core)
+
+> Ported verbatim from the .NET platform CLAUDE.md "Performance Rules" + "Data access". Always-on headlines;
+> full rationale lives in the source repo's docs/performance-and-data-correctness.md.
+
+## Data access: DbContext directly, no repository wrappers
+
+- **Handlers take `DbContext` (or `IDbContextFactory<T>`) directly. No `IFooRepository` interfaces.**
+  `DbContext` is already the Unit of Work; `DbSet<T>` is already the Repository. The only reason to wrap
+  was unit-test mocking — replaced by integration tests against Testcontainers.
+- **Reads project to DTOs inside the IQueryable:** `context.Orders.AsNoTracking().Where(...).Select(o => new OrderSummaryDto { ... }).ToListAsync(ct)` — in the handler, no method wrapping, no in-memory mapper. The projection IS the read contract. EF auto-splits projected collection navigations (no cartesian rows).
+- **Writes load the aggregate tracked and call `SaveChangesAsync`.** Optimistic concurrency tokens fire on `SaveChanges`.
+- **Exception: outbox-atomic non-handler code** (`BackgroundService` sweepers) needs an explicit transactional wrap (`BeginTransactionAsync` → work → `SaveChangesAsync` → `CommitAsync`) so Wolverine's staged outbox envelopes persist atomically.
+
+## The always-on rules
+
+- **Reads: `AsNoTracking()` + `.Select(...)` into a DTO inside the IQueryable.** Plain `AsNoTracking()` returning an entity is a half-fix.
+- **No N+1** — `Include` or projection; never query inside a `foreach` over another query's results.
+- **Non-sargable predicates defeat indexes — fix at write time.** `u.Email.ToLower() == x` can't use a B-tree index; normalize on insert (`EmailNormalized`) or use a case-insensitive collation. Leading-wildcard `LIKE '%text%'` needs `tsvector`/Elasticsearch when load justifies it.
+- **Async on request paths:** `await` everywhere. Never `.Result`/`.Wait()`/`.GetAwaiter().GetResult()` (banned at build time). Every async method propagates `CancellationToken`.
+- **Parallelize independent awaits with `Task.WhenAll`** — but not dependent ops, not a shared `DbContext` (use `IDbContextFactory<T>`), and when N calls hit the SAME service prefer a batch endpoint (one round-trip, server-atomic).
+- **Long-running work (>~1s) belongs on the message bus** — reshape as 202 Accepted: validate + persist tracking row + publish Wolverine message + return. Same for handlers themselves.
+- **Fan-out belongs on the message bus, not a synchronous handler loop** — one message per recipient/batch, throttled with `MaxDegreeOfParallelism`.
+- **Pagination:** every list endpoint paginates with a server-side cap (≤100); keyset for large offsets.
+- **Bulk ops:** `ExecuteUpdateAsync`/`ExecuteDeleteAsync`, never load thousands of rows to mutate.
+- **Optimistic concurrency:** every updatable aggregate has a token (Postgres `xmin` or row-version). Last-write-wins is not acceptable.
+- **Entity IDs use `Guid.CreateVersion7()`, not `Guid.NewGuid()`** — time-ordered, so PK inserts append-extend the B-tree index instead of fragmenting it. Apply in aggregate factories. (Not for IDs where mint time is sensitive.)
+- **`DbContext` is not thread-safe** — parallel queries require `IDbContextFactory<T>`, one per task.
+- **Migrations are immutable once applied** — destructive changes need a multi-step plan.
+- **Measure before optimizing** — BenchmarkDotNet / `dotnet-counters` / `ToQueryString()`. No caching/compiled-queries/`AsSplitQuery()` on intuition.
+- **Dapper is the sanctioned escape hatch from EF**, not a peer — only for provider-specific SQL, proven EF bottleneck, or LINQ-obscured aggregation; share the EF connection via `ctx.Database.GetDbConnection()`.

okl/scaffold/profiles/dotnet/rules/security.md

@@ -0,0 +1,42 @@
+---
+description: Security rules — IDOR, JWT, server-controlled fields, rate limiting
+paths: ["**/Endpoints/**/*.cs", "**/Features/**/*.cs", "**/ServiceDefaults/**/*.cs", "**/Program.cs"]
+---
+
+# Security (.NET microservices)
+
+> Ported verbatim from the .NET platform CLAUDE.md "Security Requirements". Each rule earned its place from a
+> dated defect.
+
+## Authorization — the IDOR pattern (CWE-639)
+
+A missing scope check is an IDOR, and IDORs slip through tests-by-omission. Canonical buyer-scoped shape:
+
+- Endpoint reads `ClaimTypes.NameIdentifier` from the JWT → passes as `RequestingBuyerId` into the query/command.
+- **Read handlers push the ownership predicate INTO the EF `Where` clause** (`Where(o => o.Id == OrderId && o.BuyerId == RequestingBuyerId)`). Non-owner rows never leave the DB — tighter than a post-materialization C# check a buggy refactor could weaken.
+- **Write handlers** load the aggregate tracked, check ownership on the loaded entity, return `false`/`null` on mismatch (NOT throw, NOT 403).
+- Endpoint translates `null`/`false` → **404**. Returning **403 leaks existence** ("this exists, just not yours"). 404 is indistinguishable from "not found."
+- **An integration test asserting buyer X cannot read buyer Y's entity is REQUIRED** for every new scoped-entity endpoint. Its absence is how the original `GET /orders/{id}` IDOR survived the codebase's lifetime.
+
+## JWT validation (explicit, not implicit)
+
+- `ValidateIssuerSigningKey = true` (explicit is auditable).
+- `ClockSkew = TimeSpan.FromSeconds(30)` — the default is **5 minutes**, which on 5-minute access tokens doubles every token's effective lifetime.
+- `ValidateAudience` / `ValidateIssuer` / `ValidateLifetime` all `true`.
+- **`RequireHttpsMetadata` is fail-closed outside Development** — never derived silently from the authority scheme. An http authority in Production must fail loudly at startup (plaintext OIDC/JWKS = MITM can inject signing keys). Legitimate internal-http opts out explicitly via `Authentication:RequireHttpsMetadata=false` (logs a warning).
+- Keycloak token policy pinned in `auth-realm.json`, never realm defaults: 5-min access tokens, single-use rotated refresh tokens, session idle 30m / max 10h.
+
+## Server-controlled fields — computed server-side, never trusted from the client
+
+Money (price, currency, tax), authorization identifiers (`BuyerId`/`SellerId` — must match JWT `sub`),
+state-machine columns (`Status`), and security flags (`IsAdmin`, `IsDeleted`) are server-controlled.
+A `[FromBody]` DTO with a `Price` field is a price-tampering vuln (client submits `Price = 0.01` for a
+$999 product). The handler fetches the authoritative value from its source (CatalogService gRPC for
+`Price`+`Currency`, JWT `sub` for buyer identity, DB for `Status`) and uses *that* — the request DTO is
+untrusted input.
+
+## Error handling & transport security
+
+- Never expose internal state, stack traces, or entity IDs. Response `traceId` uses `Activity.TraceId.ToString()` (32 hex) only, NOT `Activity.Id` (the full W3C traceparent leaks span structure).
+- HTTPS redirection enforced in prod; explicit CORS allowing only known frontend origins.
+- **Rate limiting on search + payment endpoints minimum.** In-memory limiters silently weaken to N× the limit at N instances — swap to a Redis-backed limiter once a service runs 2+ instances, with the `INCR`+`EXPIRE` pair wrapped in a Lua `EVAL` for atomicity. Single-instance today = in-memory is correct *for now* + a comment naming the swap trigger.

okl/scaffold/profiles/geospatial/README.md

@@ -0,0 +1,6 @@
+# Geospatial ML profile
+
+Canon extracted from the geospatial pipeline (`rslearn / OlmoEarth / Sentinel-1&2 / STAC / GDAL`).
+Installed to `.claude/rules/`:
+
+- `geospatial-ml.md` — label quality & time-matching, spatial CV, class_path/materialize/num_classes/temporal-decoder verification, tile-store + CPL_TMPDIR storage traps, adversarial prior-art audit

okl/scaffold/profiles/geospatial/rules/geospatial-ml.md

@@ -0,0 +1,38 @@
+---
+description: Geospatial ML rules — rslearn/OlmoEarth, label quality, spatial CV, storage
+paths: ["**/*.py", "**/*.yaml", "**/*.yml"]
+---
+
+# Geospatial ML (rslearn / OlmoEarth / Sentinel / remote sensing)
+
+> Ported from the geospatial pipeline method.md. Stack: rslearn, OlmoEarth, Sentinel-1/2, STAC,
+> Planetary Computer, GDAL. Each rule is a dated defect (error # from method.md).
+
+## Label quality — the failures that compile
+
+- **Don't rasterize every polygon as the positive class** (error #1: ~45% of positive labels were wrong — urban/agriculture/upland/water taught as geospatial). Inspect what a label layer actually contains before fitting to it.
+- **Labels and imagery must be time-matched** (error #3: NAIP 2020 labels fit against Sentinel-2 2024 = 4-year gap of self-inflicted label noise). Check the acquisition date in the source metadata of *both* sides.
+- **A model scored against wrong labels produces a meaningless metric** — verify label provenance before trusting any F1/AUC/κ.
+
+## Spatial cross-validation
+
+- **Unshuffled KFold on a spatial grid leaks nothing and looks broken** (error #11: AUC 0.23 looked like a broken encoder; it was unshuffled KFold on a spatial grid — shuffled gave 0.85). Use spatial-block or shuffled CV; refuse a convenient bad number until you've ruled out the split.
+- **Count/plot points on a map before trusting a public dataset's coordinate order** (error #12: `Virgin_River` rows had x/y transposed — 119 points in the wrong hemisphere).
+
+## rslearn / OlmoEarth scaffolding — verify, don't assert from memory
+
+- **Import every `class_path` before writing it into a config** (error #14: 5 of 23 class_paths didn't exist — every class name right, every module path wrong, written from memory, never imported; they fail at runner startup on a rented GPU). A mechanical `check-scaffold-classpaths.sh` that imports all of them is the gate.
+- **Verify materialize wrote files — never trust the exit code** (error #15: `rslearn dataset materialize` exited 0 having written zero files; `NotImplementedError` on all 238 windows swallowed into a worker pool). `verify_materialized()` checks the rasters are on disk.
+- **`num_classes` = max crosswalk id + 1 when class 0 is reserved** (error #18: `num_classes: 4` crashed `Target 4 is out of bounds` because the crosswalk emits 4 real classes and `zero_is_invalid` reserves class 0 → needs 5). A `test_class_scheme_contract.py` asserts this mechanically.
+- **Decoders on a temporal cube must read the true last-two axes** (error #19: `SegmentationPoolingDecoder` read `image.shape[1:3]` = `(timesteps, H)` on a 4-D `[bands, timesteps, H, W]` input, predicting 12×2 against a 2×2 target). Use a temporal-aware adapter; catch it with a laptop dry-run, not a GPU.
+
+## Storage & temp dirs (cloud-optimized geotiff / GDAL)
+
+- **Budget the tile store, not the output** (error #16: "~1.2 GB" estimate was right for materialized chips, ~10× low for `ingest` which pulls whole 110 km granules → 11 GB tile store).
+- **Redirect EVERY temp mechanism, not the first one** (errors #16/#17: `TMPDIR` on the boot disk filled `/` to zero; moving `TMPDIR` to the data drive still leaked 2.8 GB to `/` because **GDAL keeps its own `CPL_TMPDIR`**). Set both `TMPDIR` and `CPL_TMPDIR` to the data drive.
+
+## Novelty & prior art (the claim is falsifiable)
+
+- **Audit the literature adversarially before building** (error #5: a "nobody has mapped X" novelty claim was later found to be falsified by prior art — the geospatial repo's method.md attributes this to Evangelista et al. 2018 2-epoch change maps and a 2018 CO-RIP basin-wide RF study at κ 0.80, both found *after* building; these citations are transcribed from method.md and **not independently re-verified here — confirm against the literature before relying on them**). Run `/paper-audit` looking for reasons a paper *refutes* your novelty claim.
+- **Run the control before the experiment** — a bad number on the interesting question is uninterpretable (broken pipeline / too few labels / real effect all predict the same failure).
+- **Report the result that came out** (error #4: the mean-pooling defect was real, fixing it moved F1 0.021→0.065 vs RF 0.701 — the hypothesis was wrong, and was published wrong). A real defect is not proof it was the cause.

okl/scaffold/profiles/python-rag/README.md

@@ -0,0 +1,13 @@
+# Python RAG / agentic profile
+
+Canon extracted from the RAG service (`FastAPI / Qdrant hybrid / Redis / Postgres / Ollama / deepeval`).
+Installed to `.claude/rules/`:
+
+- `rag-pipeline.md` — retrieval-vs-identity (index & pre-filter, GROUP BY ≠ similarity), eval integrity (failure-count-first, judge≠generator, cross-tab, real fixtures), the read-only agent contract, embedder-not-hot-swappable
+- `fastapi-backend.md` — async event-loop discipline (no sync/CPU work on the loop), middleware order & auth, streaming scrub-before-emit, one-orchestrator-per-pipeline, config through the settings layer
+- `project-structure.md` — one-way app→library dependency, install-as-package (no sys.path hacks), extras for heavy deps, CLI/composition-root hygiene
+
+Note: the RAG service ships a React UI, but its own canon (docs/) contains no stated frontend rule set —
+so this profile ports backend + library rules only. React rules live in the separate, backend-agnostic
+`react` profile — stack it on if your repo has a React frontend:
+`okl scaffold --profile python-rag --profile react`.

okl/scaffold/profiles/python-rag/rules/fastapi-backend.md

@@ -0,0 +1,37 @@
+---
+description: FastAPI request-path rules — async event loop, middleware order, streaming, config
+paths: ["**/main.py", "**/app/**/*.py", "**/backend/**/*.py"]
+---
+
+# FastAPI backend (async request path)
+
+> Ported from the RAG service docs/code-review.md — each is a dated, file:line finding.
+
+## The async event loop is shared — never block it
+
+- **No CPU/IO-heavy synchronous work in an async handler** (main.py:1889: synchronous PDF work in an async handler stalled the event loop for all concurrent requests, including in-flight SSE streams). Offload to a thread/executor or a background task.
+- **No synchronous network calls inside an async path** (rag_pipeline.py:526: a synchronous `requests.post` to Qdrant inside async `retrieve()` blocked the whole event loop; semantic_cache.py:319: `clear()` uses the blocking `KEYS` command and `clear()`/`get_stats()` run sync Redis calls on the async loop). Use the async client.
+- **Don't drive a loop-bound async provider via `asyncio.run()` on executor threads** (document_grader.py:363: broke in the default config and silently disabled CRAG grading).
+
+## Middleware order and auth are security-critical
+
+- **Auth vs CORS ordering** (main.py:567: `APIKeyMiddleware` added after `CORSMiddleware` made it outermost, so CORS-preflight OPTIONS got 401 and blocked all browser clients). Order middleware deliberately; test a browser preflight.
+- **A rate-limit tier must not be granted on an unvalidated header** (main.py:527: the higher per-key tier was granted to any request merely carrying an `X-API-Key` header — the key was never validated, so each forged key got its own quota bucket).
+- **`slowapi` finds the request parameter by NAME** (main.py:978: `/query/stream` 500'd on every request when rate limiting was on because the parameter named `request` was the Pydantic body). Name the `Request` parameter `request`.
+
+## Streaming must not bypass the validation the non-streaming path runs
+
+- **Scrub/validate before the first token reaches the client** (main.py:1218: `AnswerScrubber` PII redaction was bypassed on `/query/stream` — raw LLM tokens streamed before validation ran). Streaming scrub-before-emit is the rule.
+- **Don't reimplement a pipeline per endpoint** (main.py:976: `/query/stream` reimplemented ~300 lines of the `/query` pipeline and drifted — no audit log, no metrics, no OTel span — while config claimed audit covered both). One orchestrator behind both `/query` and `/query/stream`.
+
+## Errors, persistence, admin state
+
+- **Never leak raw exception text to clients** (main.py:1288: raw exception text leaked on both endpoints, bypassing the DEBUG gate the general exception handler implements). Return a generic error + correlation id.
+- **Non-essential persistence stays off the critical path** (main.py:928: trace + conversation writes sat unguarded on the request path, so a Postgres/Redis outage turned an already-generated answer into a 500). Make observability writes best-effort.
+- **Don't mutate shared pipeline state mid-flight** (main.py:2120: `POST /admin/models` mutated shared pipeline state with no lock, reached into private methods, and left `app.state.llm_provider` stale so metrics/audit reported the wrong model). Guard with a lock; go through the public seam.
+- **An advertised parameter that's a silent no-op is a defect** (main.py:1539: `GET /api/search` advertised a `mode` param that was silently ignored).
+
+## Config layering — one settings source
+
+- **Read config through the settings layer, not `os.environ` at import time** (opik_tracer.py:66 and MODEL_PROFILES: `os.getenv` at import time while `config.py` defined the same settings via pydantic-settings, so values set only in `.env` silently left features disabled; MODEL_PROFILES was even keyed on a dev VM's absolute path).
+- **One embedding-dimension source of truth** (rag_pipeline.py:288: resolving `EMBEDDING_DIM` via `os.environ.get(..., 768)` bypassed the backend's `settings.EMBEDDING_DIM=1024` and silently built a cache index with the wrong vector dimension). Two parallel pydantic Settings systems with conflicting defaults is the root cause — collapse them.

okl/scaffold/profiles/python-rag/rules/project-structure.md

@@ -0,0 +1,28 @@
+---
+description: Python project structure — one-way dependency, packaging, CLI hygiene
+paths: ["**/pyproject.toml", "**/Dockerfile*", "**/main.py", "**/src/**/*.py"]
+---
+
+# Project structure & packaging (Python)
+
+> Ported from the RAG service docs/project-structure.md + code-review.md cross-cutting findings.
+
+## One dependency direction, installed as a package
+
+- **The app imports the library; the library never imports the app.** Two Python roots, one direction:
+  the reusable library in `src/<pkg>/`, the app in `app/` consuming it as an *installed* package.
+- **Install the library as a package — no `sys.path`/`PYTHONPATH` hacks** (Dockerfile:74: the library was never installed, just path-hacked via `PYTHONPATH=/app/src` with dependencies hand-mirrored in `requirements.txt`, so the two manifests drifted; rag_pipeline.py:36: a `sys.path` hack counted two `..` hops too many and pointed at a directory that never existed — dead code documenting a false import mechanism). `pip install .` against a curated manifest, no path edits.
+- **Heavy optional capabilities live behind extras** (pyproject.toml:20: the library declared streamlit, deepeval, docling, sentence-transformers, pytesseract, langchain as *mandatory* core deps though they serve only CLI/eval/dashboard paths — making the package uninstallable in a lean backend and forcing the `requirements.txt` workaround). Keep `pip install .` lean; gate the rest behind `[ingestion]`, `[eval]`, `[dashboard]` extras.
+
+## Organize by seam, not concern-per-folder
+
+- Feature/service code stays adjacent by seam so a change to a provider Protocol and its consumers is one directory away, not six. Every standard concern (app shell, agent core, memory, routing, security, eval, observability, deploy) has exactly one home.
+- Deliberate deviations are allowed and documented (no agent-framework folder when the loop is ~200 explicit lines; no vendor security wrapper when the harness is in-repo and readable).
+
+## CLI / composition-root hygiene
+
+- **Consistent embedder defaults across commands** (main.py:551: `ingest` defaulted to `--embedder openai` (1536-dim) but `query` defaulted to `--embedder voyage` (1024-dim), so the documented happy path broke).
+- **Don't ship dead course/tutorial artifacts as commands** (main.py:1318: 8 of 16 CLI commands were course-week artifacts whose default paths didn't exist; main.py:1 tutorial narration was ~1/3 of the file, burying the signal).
+- **Fail the same way on the same bad input** (main.py:567: `query` silently swallowed an invalid `--embedder` (`except ValueError: pass`) and proceeded with a None dimension while `ingest` hard-failed on the same input).
+- **Never rewrite a data file in place with a plain `open('w')`** (main.py:472: `dedup --apply` rewrote `documents.jsonl` in place, so a crash mid-write destroyed the processed corpus). Write to a temp file and atomically rename.
+- **Business logic belongs in a service, not the composition root** (main.py:1133: `eval-pairwise`/`build-golden-dataset` embedded prompt templates, dual LLM clients, and regex JSON parsing inside the CLI entrypoint, contradicting the file's own stated design; Qdrant payload-index creation was inlined in the ingest handler instead of the infrastructure layer).

okl/scaffold/profiles/python-rag/rules/rag-pipeline.md

@@ -0,0 +1,73 @@
+---
+description: RAG pipeline rules — retrieval vs identity, eval integrity, agent contract
+paths: ["**/*.py"]
+---
+
+# RAG / agentic pipeline (Python / FastAPI / Qdrant / eval)
+
+> Ported from the RAG service docs/findings-log.md + agent-contract.md. Stack: FastAPI, Qdrant (hybrid
+> dense+BM25+RRF), Redis, Postgres, Ollama/OpenAI-compatible LLM, deepeval. Each rule is a numbered
+> finding.
+
+## The through-line (the one bug wearing different clothes)
+
+> **Something inferred an answer by resemblance when an exact answer was available.**
+> The fix is always the same move: **make the model choose the constraint, and make code satisfy it.**
+
+- Semantic search *ranks* by content — it cannot distinguish one document from another (every contract
+  has a termination clause). **Document identity must be indexed and pre-filtered, not ranked** (Part 3).
+- A corpus-wide question (`multi-12`/`multi-13`: "list every company", "do any two docs share one?") is
+  a **`GROUP BY`, not a similarity question** — a ranked retriever cannot answer it at any top-k, because
+  a question about the whole corpus has no best-matching chunk. Read the index and aggregate in code (Part 4).
+- Don't match filename tokens loosely when the filename has a grammar (EDGAR `COMPANY_DATE-EX-N.N-TYPE`):
+  `"sla" in "Tesla"`, exhibit numbers `10.1` indexed as companies. **Parse the structure; match on token
+  boundaries; require a party to contain two consecutive letters** (Part 3).
+
+## Eval integrity (the most dangerous defects)
+
+- **A metric that cannot report its own failure rate is not a metric** (#1: "LLM Judge 5.0/5.0" while 19
+  of 20 cases crashed — the harness averaged only the completed ones). The summary **leads with its own
+  failure count** and prints `❌ RESULTS NOT USABLE` above a 20% failure rate.
+- **The judge must not grade its own homework** (#5: the LLM judge defaulted to the same model as the
+  generator — a mirror, not a signal; its default was even an embedding model that can't generate). Judge
+  ≠ generator, always.
+- **Run the error-analysis cross-tab** `retrieval_hit × judge_score` (#6). It's what revealed *generation*,
+  not retrieval, was the dominant failure mode — after a whole session optimizing retrieval. The conclusion
+  "agentic retrieval is architecturally weaker" was exactly backwards and got the eval-results doc retracted.
+- **Fixtures you invented cannot falsify assumptions you hold** (Part 3): entity tests used invented
+  fixtures (`Apple_10K.html`) and passed at 100% while the live index had `10.1` as a company. Tests are
+  now the **25 real filenames, verbatim**.
+- **Use the instrumentation you already have** (#6 meta-lesson): OpenTelemetry, Prometheus, per-stage trace
+  timings existed the whole time while debugging happened by `curl` and `grep`.
+
+## Measure the same system
+
+- **Runs must target the same corpus/config** (#2: four Qdrant collections existed — `python-rag-service_hybrid`,
+  `python-rag-service_ids`, `python-rag-service_full` (zero entities), `python-rag-service_entities` — and the container was
+  hand-pointed at one while `config.py` named another). One canonical collection; strays deleted + tombstoned.
+- **Give each arm the same budget** (#4: the agent's `search_corpus` inherited `top_k=3` while classic used
+  8 on the same question — comparing 3 chunks against 8 and blaming the architecture).
+- **A tool that throws on every call makes the agent measure a broken tool, not an architecture** (#3:
+  `search_filtered` defaulted to a paid Voyage reranker with no key and threw every call; the agent burned
+  its whole step budget retrying). Empty results return the entity vocabulary so the agent can self-correct.
+
+## The agent contract (read-only tools, budgets, allowlist)
+
+- **The agent's capability surface is the tool registry — allowlist, not denylist.** A tool exists only if
+  registered; unknown names are never executed (`test_unknown_tool_is_rejected` — "the loop must never
+  invent capabilities").
+- **Budgets are explicit and env-overridable:** `AGENT_MAX_STEPS`, `AGENT_TOKEN_BUDGET`,
+  `AGENT_TOOL_TIMEOUT_S`. Exhaustion finishes with what was gathered and flags the trace. `finish` is the
+  explicit stop signal; there is no unbounded path through the loop.
+- **Build side-effect machinery with the first mutating tool, not speculatively.** Adding a read-only tool
+  = registry entry + tests + a doc row. A tool with side effects requires argument-schema validation, a
+  pre-execution control mode (audit/approval/block), and severity-gated alerting *before* it ships — none
+  of which exists today, deliberately.
+
+## Config / model swapping
+
+- **The LLM is hot-swappable (any OpenAI-compatible endpoint, no re-index); the embedder is NOT** — its
+  output dimension is baked into the Qdrant collection at ingest. Changing `EMBEDDER_TYPE` means setting
+  `EMBEDDING_DIM` to match AND re-indexing.
+- **Library dependency direction is one-way:** the app imports the library, never the reverse; the library
+  is pip-installed (no `PYTHONPATH`/`sys.path` edits). Heavy optional capabilities live behind extras.

okl/scaffold/profiles/react/README.md

@@ -0,0 +1,18 @@
+# React frontend profile
+
+Portable React SPA canon, extracted verbatim from the .NET platform's `frontend/CLAUDE.md` (the .NET platform
+storefront). **Backend-agnostic** — stack it onto any backend profile whose repo has a React frontend:
+
+    okl scaffold --profile dotnet --profile react
+    okl scaffold --profile python-rag --profile react
+
+Installed to `.claude/rules/`:
+
+- `frontend.md` — path-scoped to `frontend/**` and `**/frontend/**`: TanStack Query server state
+  (useEffect-fetching banned), effects discipline ("You Might Not Need an Effect"), React-Compiler
+  render/bundle perf (don't reflexively memoize; ≤200 KB gz budget), PKCE SPA auth + in-memory tokens
+  (BFF trade-off documented), MSW + Playwright testing.
+
+Reference stack: Vite + React 19 + TS strict, CSR SPA, TanStack Query/Router, Zustand, Tailwind v4 +
+shadcn/ui, oidc-client-ts → Keycloak. Deep reference: the vendored `vercel-react-best-practices`
+skill (70 rules), where the canon wins on any disagreement.