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

okl/scaffold/profiles/react/rules/frontend.md

@@ -0,0 +1,57 @@
+---
+description: React storefront canon — server state, effects, render/bundle perf, SPA auth
+paths: ["frontend/**/*.tsx", "frontend/**/*.ts", "**/frontend/**/*.tsx", "**/frontend/**/*.ts"]
+---
+
+# React canon (frontend SPA)
+
+> Portable React rules, ported verbatim from the .NET platform's `frontend/CLAUDE.md` (the .NET platform
+> storefront) — but backend-agnostic: stack these onto ANY backend profile (dotnet, python-rag, …)
+> whose repo has a React frontend. Reference stack: Vite + React 19 + TypeScript (strict), CSR SPA;
+> TanStack Query v5 + Router; Zustand (small UI globals only); Tailwind v4 + shadcn/ui; oidc-client-ts
+> → Keycloak (auth-code + PKCE); React Compiler on. Deep reference: the vendored
+> `vercel-react-best-practices` skill (70 rules) — **but this canon wins where they disagree.**
+>
+> Where a rule cites "the backend" (VSA feature folders, server-controlled fields, cache-in-write-path,
+> measure-before-optimizing), the parallel holds against whatever backend you pair this with.
+
+## Architecture
+
+- **Feature folders mirror the backend's VSA.** `src/features/<capability>/` owns its components, hooks, api calls, types. `src/shared/` is domain-agnostic; `src/core/` is singletons (query client, router, auth); `src/app/` is a thin shell — no business logic.
+- **Feature boundaries are enforced, not conventional.** Features never import another feature's internals — only via its `index.ts` public API; `shared/` never imports from features. ESLint `import/no-restricted-paths` makes violations build errors.
+- **Barrel files are intentional** — a feature's `index.ts` exports its public surface explicitly; everywhere else import directly (wildcard re-export barrels defeat tree-shaking).
+- **Promotion to `shared/` requires proven reuse** (2–3 features independently need it). Speculative abstraction is the same dead weight as speculative interfaces in the backend.
+
+## Server state (the biggest rule)
+
+- **All server data flows through TanStack Query. Fetching in `useEffect` is banned** — hand-rolled effect-fetching badly reimplements dedup/caching/race-handling/retries the library gives you.
+- **Query keys are a typed convention** `[feature, entity, params]` (e.g. `['catalog','products',{search}]`); key factories live in the feature's `api/` module.
+- **Mutations invalidate (or update) their affected queries in the same mutation definition** (`onSuccess`), never "later" or via refetch-on-focus luck — the backend's "cache invalidation in the write path" rule, client-side.
+- **Server data is never copied into `useState`** — render from the query result; copying makes a second source of truth that goes stale.
+
+## Effects discipline ("You Might Not Need an Effect")
+
+- **An Effect is only for synchronizing with an external system** (browser API, non-React widget, subscription). Everything else has a better tool: derived data → **calculate during render** (`useMemo` only if measured-expensive); reset-on-prop-change → **`key` prop**; "user did X" (POST/notify/navigate) → **event handler**, not an effect watching a flag; external store → **`useSyncExternalStore`**; state chains → compute in the handler; notify parent → call the callback in the handler or lift state up.
+- **Effect dependencies are facts, not knobs.** Never lie to the dependency array to control *when* an effect runs — restructure instead. `eslint-plugin-react-hooks` `exhaustive-deps` is an error, not a warning.
+
+## Render & bundle performance
+
+- **Don't fight the React Compiler.** No reflexive `useMemo`/`useCallback`/`memo` — the compiler memoizes; manual memoization needs a profiler trace (the backend's "measure before optimizing"). Structural cases the compiler can't fix are still yours: don't define components inside components; hoist static JSX / default non-primitive props; functional `setState` for stable callbacks; refs for transient high-frequency values.
+- **No request waterfalls on the critical path** — route loaders start queries before render; independent fetches run in parallel (`Promise.all` / parallel `useQuery`); Suspense streams what's ready. A fetch waiting on a render waiting on a fetch is the client-side N+1.
+- **Route-level code splitting is the default**; heavy below-the-fold components via dynamic import; third-party scripts after hydration. **Initial bundle budget ≤ 200 KB gz, CI-checked.**
+- **Virtualize lists past ~50 items.** **`startTransition`/`useDeferredValue` for non-urgent updates** (search-as-you-type) to keep input latency flat.
+
+## Security
+
+- **Auth flow: authorization code + PKCE, full stop.** The OAuth Browser-Based Apps BCP makes PKCE a MUST for SPA public clients and deprecates the implicit flow — no `response_type=token` anywhere.
+- **Tokens live in memory (oidc-client-ts session), never `localStorage`** — XSS that reads storage steals tokens. **Documented trade-off:** the BCP ranks browser-held tokens as the least secure of its three patterns and recommends a BFF (tokens server-side, browser gets an HttpOnly cookie) for sensitive apps; acceptable here only because it's a demo storefront with fake data — if it ever fronts real user data, the BFF becomes the required shape.
+- **Refresh tokens: rely on Keycloak's rotation** (BCP requires rotation/sender-constraining + bounded lifetime for SPA refresh tokens).
+- **The client never computes or trusts money/authorization fields** — display what the server returns (backend's server-controlled-fields rule; the cart total is a preview, the authoritative total comes back from `POST /orders`).
+- **No secrets in the bundle** — `import.meta.env` carries public config only.
+
+## Testing & conventions
+
+- **Test user-visible behavior, not implementation** — RTL queries by role/label; no testing hook internals or state shapes.
+- **MSW mocks at the network boundary** — component/integration tests against mocked REST handlers per service (including error and slow cases).
+- **Every feature ships happy path + error path + loading/empty state tests.** **Playwright E2E for the saga walk-through** runs against the real Aspire stack — regression gate and demo script both.
+- Components `PascalCase.tsx`, hooks `useX.ts`, feature folders `kebab-case`, one component per file, named exports (default only where the router requires). TypeScript strict; no `any` (`unknown` + narrowing); API response types derived from backend DTO shapes.

okl/scaffold/registries/RETRACTIONS.md

@@ -0,0 +1,19 @@
+# Retractions
+
+Claims this project once made and has since found to be false. A retraction is a **receipt**, not a
+deletion — the wrong claim stays visible with its correction so it cannot be quietly restated.
+
+The `retractions` gate fails any tracked doc that states a retracted claim without also retracting it.
+
+## Format
+Each entry: a stable `id`, the retracted claim (quoted), why it is false, and the date/commit.
+
+<!-- <<FILL: retractions as you earn them. Example from the RAG service: -->
+<!--
+### R-0001 — "agentic's retrieval is architecturally weaker than classic"
+- **Retracted:** the conclusion in `docs/rag-mode-eval-results.md`.
+- **Why false:** the agent's primary tool (`search_filtered`) threw on every call and it was given
+  top_k=3 vs classic's 8. It measured broken instrumentation, not an architecture. Error-analysis
+  cross-tab showed generation, not retrieval, is the dominant failure mode.
+- **Date/commit:** 2026-07 / findings-log Part 2.
+-->

okl/scaffold/registries/tombstones.txt

@@ -0,0 +1,7 @@
+# Tombstones — retired identifiers that must not be resurrected.
+# One identifier per line. The `tombstones` gate fails any doc/comment/config that reintroduces one.
+# Format:  <identifier>  <TAB>  <reason / what replaced it>  <TAB>  <date>
+#
+# <<FILL as you retire things. Examples:>>
+# python-rag-service_full	empty-entity stray collection; canonical is python-rag-service_hybrid	2026-07
+# python-rag-service_ids	stray collection; deleted in 36db337	2026-07

okl/scaffold/root/CLAUDE.md

@@ -0,0 +1,55 @@
+# {{REPO}} — agent instructions (canon, surface 2)
+
+> New session? Read `.claude/rules/` (loaded by path) and run `/feature-spec` before non-trivial work.
+> This file is the **always-on canon**. Keep it lean — target ~60–150 lines. Detail lives in
+> `.claude/rules/*.md` (path-scoped), `.claude/skills/` (on-demand), and `docs/` (deep reference).
+> CI enforces a size budget (warn 200 / fail 300 lines). This is surface 2 of the encoding loop.
+
+## The method (portable — do not delete)
+
+This repo runs the **encoding loop**: a trigger (planning, a bug, a review finding, an audit)
+produces a rule; the response is always **pick the smallest surface → encode it → promote down the
+spectrum as it earns its keep**. Five surfaces, softest→strongest (1→5 *is* moving down):
+
+1. Deep reference — `docs/` + diagrams (passive)
+2. Always-on canon — this file + `.claude/`
+3. Procedure rituals — `.claude/skills/` + `.claude/commands/` (user-invoked)
+4. PR-review automation — `.coderabbit.yaml` + `.claude/agents/architecture-reviewer.md`
+5. Mechanical gates — CI, tests, hooks (build fails if violated)
+
+**Before starting work, the pre-task hook injects the org's relevant lessons** via `okl check`
+(surface 6 — the cross-repo layer). Read them. Retractions, tombstones, and armed gates in that
+briefing are binding. If it says a claim is retracted, do not restate it as fact.
+
+**When you learn something worth keeping** ("never write this again" / "always do this when"),
+encode it the same session at the smallest sufficient surface, and `okl record` it — `scope=org`
+if it is a fact about the world (prior art, an API contract, a data gotcha), `scope=repo` if it is
+a quirk of this codebase only. A merged fix without the encoded rule is a half-finished job.
+
+## Always-on rules (keep few; most rules belong in `.claude/rules/` or skills)
+
+- Never commit secrets, `.env` files, or credentials.
+- Every non-trivial change starts with `/feature-spec` (value gate + significance check).
+- Any spec/plan/scaffold **assertion** ("these paths are correct", "this config is valid") earns a
+  mechanical `validate` step before it is trusted — never assert from memory. (SDD's one load-bearing rung.)
+- Report the result that came out, especially when it disproves your own hypothesis.
+- Verify a gate by making it FAIL on real drift before trusting it to pass.
+
+<!-- <<FILL: STACK-SPECIFIC ALWAYS-ON RULES>>
+     Add the handful of rules every session in THIS repo needs (language, framework, house style).
+     Keep each to one bolded headline + one paragraph; move the rationale to docs/ or a rule file.
+     Delete this comment when filled. Examples of what belongs here vs. a path-scoped rule file:
+       - belongs here: "All money math is server-computed, never trusted from the client."
+       - belongs in .claude/rules/db.md (paths: **/*.sql): EF/query conventions.
+-->
+
+## Build & test
+
+<!-- <<FILL: BUILD/TEST COMMANDS>>  e.g. `make test`, `dotnet build`, `pytest -q`, `npm run ci` -->
+
+## Encoding surfaces in this repo (auto-maintained)
+
+- Registries: `registries/RETRACTIONS.md`, `registries/tombstones.txt`
+- Gates: `gates/` (run via `gates/run-gates.sh`; required in CI)
+- Evals: `evals/` (golden set from real failures; gates on measured behavior)
+- Knowledge layer: `okl check` / `okl record` (see `.okl/config.json`)

okl/scaffold/root/METHOD.md

@@ -0,0 +1,64 @@
+# The Method — portable engineering discipline (the encoding loop)
+
+> This is the method in its entirety, distilled from three repositories that run it across three
+> different stacks: **the .NET platform** (.NET microservices), **the geospatial pipeline** (geospatial /
+> rslearn / OlmoEarth), and **the RAG service** (Python / FastAPI / RAG). A rule is in this file — the
+> *portable* skeleton — only if it showed up in more than one of them independently. Stack-specific
+> rules live in `.claude/rules/*.md` and the `<<FILL>>` slots, not here.
+
+## The core (the whole method in four sentences)
+
+1. **AI-assisted work fails by producing output that is fast, fluent, plausible, and wrong.** Every
+   rule merely *documented* drifts; every rule *mechanized* holds. So the method is not exhortation —
+   it is surfaces that make the right thing automatic and the wrong thing fail loudly.
+2. **The encoding loop:** a trigger (planning, a bug, a review finding, an audit, an incident)
+   surfaces a rule. The response is always *pick the smallest sufficient surface → encode it →
+   promote it down the spectrum (toward mechanical) only as it earns its keep.* It is a ratchet: it
+   does not slip back.
+3. **Six surfaces, softest→strongest:** (1) deep reference `docs/`, (2) always-on canon `CLAUDE.md`
+   + `.claude/rules/`, (3) procedure rituals `.claude/skills/` + commands, (4) PR-review automation
+   `.coderabbit.yaml` + `architecture-reviewer`, (5) mechanical gates CI/tests/hooks, (6) the
+   cross-repo org knowledge layer (`okl`). 1–2 are Tier 1, 3–4 Tier 2, 5 Tier 3; 6 spans repos.
+4. **A surface nobody runs is documentation, not enforcement.** If a rule is not read or executed on
+   the path where it matters, it will drift — so the method's own defects are dated, receipted, and
+   registered, and the gates are verified by making them *fail* on real drift before trusting them.
+
+## The seven portable rules (each earned in ≥2 of the three repos)
+
+1. **Don't ask a model to infer what you can look up.** Assertions written from memory (class paths,
+   entity identities, config validity) are the single most common defect class across all three
+   repos. Every such assertion earns a mechanical `validate` step. *Let the model choose the
+   constraint; make code satisfy it.*
+2. **A signal that cannot report its own failure is not a signal.** An exit code of 0 with zero
+   outputs; a judge that averages only the runs that didn't crash; a "PASS" with no fixture behind
+   it. Every gate and every metric must be able to say when it is unreliable, and say it first.
+3. **Verify the layer before you build on it.** Confirm the thing you depend on actually works —
+   with a real, non-trivial input — before you stack more on top. (A graph planned on a 0%-populated
+   entity layer; a model trained on a 0-file materialized dataset.)
+4. **Fixtures you invented cannot falsify assumptions you hold.** Test against real data sampled from
+   the actual corpus/inputs, not fixtures written by the same person who wrote the code under test.
+   The adversarial audit (`/paper-audit`) exists to attack your own confident claims.
+5. **Report the result that came out** — especially when it disproves your hypothesis. When a result
+   turns out wrong, *retract it in a registry*, don't quietly delete it. The retraction is a receipt.
+6. **Record decisions, including the ones you rejected and why.** "Options considered and rejected"
+   is as valuable as what you built. An ADR is append-only: supersede, never edit-to-erase.
+7. **Use the instrumentation you already have.** The trace, the metric, the log, the cross-tab —
+   build the observability once and then actually read it, instead of debugging by `grep`.
+
+## What is deliberately NOT in this file (stack-specific — goes in FILL slots / rule files)
+
+- Framework rules (VSA vs Clean, Wolverine handler discovery, EF outbox) → the .NET platform's canon.
+- Domain rules (spatial cross-validation, class-scheme crosswalks, GDAL temp dirs) → the geospatial repo.
+- Pipeline rules (reranker config, Qdrant pre-filter, corpus-aggregate vs ranked retrieval) → the RAG service.
+
+Each of those is *real method* — but it is fill, not skeleton. The kit ships the slots; you drop the
+stack rules in per repo (`.claude/rules/<area>.md` with a `paths:` glob), and `okl record --scope repo`
+them so they are enforced without polluting another repo's `okl check`.
+
+## Sources
+
+Ported verbatim from the three repositories' own method documents:
+`the geospatial pipeline/docs/method.md`; the .NET platform `CLAUDE.md` + `CONTEXT.md` + `.github/AI_WORKFLOW.md`;
+the RAG service `docs/agent-contract.md` + `docs/findings-log.md`. Current-tool practices (Claude Code
+plugins, subagent memory frontmatter, `.claude/rules` path-scoping, hook exit-code-2 blocking) verified
+against the official Claude Code docs.

okl/scaffold_cmd.py

@@ -0,0 +1,110 @@
+"""`okl scaffold` — stamp the portable method kit into a repo.
+
+Copies the template tree shipped inside the package (src/okl/scaffold/) into the target repo,
+renaming `claude/` -> `.claude/` (the package can't ship a dotfile dir on some filesystems), and
+substituting `{{REPO}}`. Never overwrites an existing file unless --force; prints a FILL worklist.
+"""
+from __future__ import annotations
+
+import shutil
+from pathlib import Path
+
+SCAFFOLD_ROOT = Path(__file__).parent / "scaffold"
+
+# (src relative to scaffold/, dst relative to repo root). `{c}` is the claude dir name
+# (".claude" in real use; overridable only so the logic is testable inside sandboxes that
+# forbid creating a literal ".claude" path).
+def _layout(c: str = ".claude"):
+    return [
+        ("root/CLAUDE.md", "CLAUDE.md"),
+        ("root/CLAUDE.md", "AGENTS.md"),   # same source, two names: Claude Code + every other agent
+        ("root/METHOD.md", "METHOD.md"),
+        ("claude", c),              # dir: skills/agents/commands/rules
+        ("gates", "gates"),
+        ("registries", "registries"),
+        ("evals", "evals"),
+        ("ci/method-gates.yml", ".github/workflows/method-gates.yml"),
+        ("ci/okl-verify.yml", ".github/workflows/okl-verify.yml"),
+        ("hooks/userpromptsubmit-okl-check.sh", f"{c}/hooks/userpromptsubmit-okl-check.sh"),
+        ("hooks/stop-okl-encode.sh", f"{c}/hooks/stop-okl-encode.sh"),
+        ("hooks/hooks.json", f"{c}/hooks/hooks.json"),
+        ("MANIFEST.md", "docs/method-kit-manifest.md"),
+    ]
+
+PLUGIN_LAYOUT = [
+    ("plugin/plugin.json", "plugin.json"),
+]
+
+
+def _copy(src: Path, dst: Path, repo: str, force: bool, written: list, skipped: list):
+    if src.is_dir():
+        for child in src.rglob("*"):
+            if child.is_file():
+                rel = child.relative_to(src)
+                _copy_file(child, dst / rel, repo, force, written, skipped)
+    else:
+        _copy_file(src, dst, repo, force, written, skipped)
+
+
+def _copy_file(src: Path, dst: Path, repo: str, force: bool, written: list, skipped: list):
+    if dst.exists() and not force:
+        skipped.append(dst)
+        return
+    dst.parent.mkdir(parents=True, exist_ok=True)
+    text = None
+    try:
+        text = src.read_text()
+    except (UnicodeDecodeError, ValueError):
+        shutil.copy2(src, dst)  # binary
+        written.append(dst)
+        return
+    dst.write_text(text.replace("{{REPO}}", repo))
+    if dst.suffix == ".sh":
+        dst.chmod(0o755)
+    written.append(dst)
+
+
+def list_profiles() -> list[str]:
+    d = SCAFFOLD_ROOT / "profiles"
+    return sorted(p.name for p in d.iterdir() if p.is_dir()) if d.is_dir() else []
+
+
+def scaffold(target: str = ".", repo: str | None = None, force: bool = False,
+             plugin: bool = False, claude_dir: str = ".claude",
+             profile: str | list[str] | None = None) -> dict:
+    root = Path(target).resolve()
+    root.mkdir(parents=True, exist_ok=True)
+    repo = repo or root.name
+    written: list[Path] = []
+    skipped: list[Path] = []
+
+    # Profiles are composable — stack a backend profile with react, etc.
+    profiles = [profile] if isinstance(profile, str) else list(profile or [])
+    if profiles:
+        avail = list_profiles()
+        for p in profiles:
+            if p not in avail:
+                raise ValueError(f"unknown profile {p!r}; available: {', '.join(avail) or '(none)'}")
+
+    layout = _layout(claude_dir) + (PLUGIN_LAYOUT if plugin else [])
+    for src_rel, dst_rel in layout:
+        _copy(SCAFFOLD_ROOT / src_rel, root / dst_rel, repo, force, written, skipped)
+
+    # Each profile drops its stack's verbatim canon into .claude/rules/ (+ a README).
+    for p in profiles:
+        prof_root = SCAFFOLD_ROOT / "profiles" / p
+        _copy(prof_root / "rules", root / claude_dir / "rules", repo, force, written, skipped)
+        _copy(prof_root / "README.md", root / claude_dir / "rules" / f"_PROFILE_{p}.md",
+              repo, force, written, skipped)
+
+    # find FILL slots across everything just written
+    fills = []
+    for p in written:
+        try:
+            for i, line in enumerate(p.read_text().splitlines(), 1):
+                if "<<FILL" in line:
+                    fills.append(f"{p.relative_to(root)}:{i}")
+        except (UnicodeDecodeError, ValueError):
+            pass
+    return {"repo": repo, "root": str(root), "written": [str(p.relative_to(root)) for p in written],
+            "skipped": [str(p.relative_to(root)) for p in skipped], "fills": fills, "plugin": plugin}