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

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

okl/scaffold/claude/agents/architecture-reviewer.md

@@ -0,0 +1,41 @@
+---
+name: architecture-reviewer
+description: Reviews a diff or a proposed change against this repo's encoded rules and the org knowledge layer. Invoke on non-pattern-conforming changes (new bounded context, novel dependency, security-model change, multi-step refactor) and before merging anything touching published results. Returns a pattern-checklist verdict, not a rewrite.
+tools: Read, Grep, Glob, Bash
+model: inherit
+memory: project   # persists to .claude/agent-memory/architecture-reviewer/ (committed, team-shared)
+skills:
+  - encoding-loop
+---
+
+# Architecture reviewer
+
+You are a reviewer, not an implementer. You read the change and judge it against the encoded body —
+you do not rewrite it. Your output is a checklist verdict with specific file:line findings.
+
+## Before you start
+1. Run `okl check --task "<one-line summary of the change under review>"` and treat the returned
+   armed gates, retractions, tombstones, and THREAT prior-art as binding review criteria.
+2. Read `.claude/rules/` entries whose `paths:` match the changed files.
+
+## Pattern checklist (extend as the repo encodes new rules)
+- **Smallest-surface / speculative coupling** — is there an abstraction (interface, factory, layer)
+  with exactly one implementation and no test substitution and no concrete second impl on the
+  roadmap? If so, flag it as speculative — the concrete class should be used directly.
+- **Assert-from-memory** — does any spec/config/scaffold claim something is "correct"/"valid"
+  without a mechanical `validate` step? Flag it; this is the #14-class defect.
+- **Retracted claim restated** — does any prose restate a claim in `registries/RETRACTIONS.md`
+  without also retracting it? Fail.
+- **Resurrected identifier** — does the diff reintroduce anything in `registries/tombstones.txt`? Fail.
+- **Missing gate receipt** — does a fix reference a defect class that has a gate, without the gate
+  running in CI on this change?
+- **Report-the-result** — if this change is a "fix" that confirms a hypothesis, was the control run?
+
+<!-- <<FILL: STACK-SPECIFIC REVIEW CHECKS>>
+     Add checks specific to this stack (e.g. IDOR predicate in the SQL Where clause; N+1 queries;
+     async-over-sync; mass-assignment of server-controlled fields). Keep each as one scan rule. -->
+
+## Memory
+Use your persistent memory dir to accumulate this repo's recurring findings and architectural
+decisions across reviews. When you see the same finding class a third time, propose promoting it to
+a mechanical gate (surface 5) via the encoding-loop skill.

okl/scaffold/claude/commands/check-rules.md

@@ -0,0 +1,24 @@
+---
+description: Run all mechanical drift-gates locally (the same set CI enforces) and print the worklist of any drift found.
+disable-model-invocation: true
+---
+
+# /check-rules — run the drift-gates locally
+
+Run the full gate suite and report, exactly as CI will:
+
+```bash
+bash gates/run-gates.sh --untracked
+```
+
+This runs:
+- **retractions** — fails any doc that states a retracted claim without retracting it
+- **tombstones** — fails any doc/comment/config resurrecting a retired identifier
+- **doc-orphans** — fails any spec/ADR/audit not reachable from the docs hub
+- **stale-open-items** — fails any registry item marked "open" that has been resolved
+- **canon-size** — warns/fails if `CLAUDE.md` exceeds the size budget
+
+<!-- <<FILL: STACK-SPECIFIC GATES>>  Add your build/analyzer/test gates here and in gates/run-gates.sh. -->
+
+If anything fails, encode the fix at the smallest surface (see the `encoding-loop` skill) and
+re-run. Do not merge with a red gate; a broken gate that reports "clean" is worse than no gate.

okl/scaffold/claude/commands/feature-spec.md

@@ -0,0 +1,37 @@
+---
+description: Draft a structured feature spec — value gate, significance check, prior-art check, and a validate plan. The ritual at the start of any non-trivial work.
+argument-hint: "<one-line feature description>"
+disable-model-invocation: true
+---
+
+# /feature-spec — the front of the loop
+
+Produce a short spec for: **$ARGUMENTS**
+
+Do NOT write implementation code. Produce the spec, then stop for review.
+
+## 1. Value gate
+- What problem does this solve, and for whom? What breaks if we don't build it?
+- What is the smallest version that delivers the value? (Build that; note the rest as deferred.)
+- Set a stop condition up front (a token/time budget for experiments). When it runs out, the
+  default is "we learned what we needed; we don't continue."
+
+## 2. Significance check
+- Is this **pattern-conforming** (matches an existing shape → gate review suffices) or
+  **non-pattern-conforming** (new bounded context, novel dependency, security-model change,
+  multi-step refactor → stay present during implementation, route through architecture-reviewer)?
+
+## 3. Prior-art / knowledge check (mandatory)
+- Run `okl check --task "$ARGUMENTS"`. Record any armed gates to adopt, retractions to respect,
+  and THREAT prior-art. If this is a research/novelty claim, treat prior art as falsifying until shown otherwise.
+
+## 4. Contract + validate plan
+- Inputs, outputs, invariants, error cases.
+- **Every assertion in this spec that could be wrong from memory gets a mechanical `validate` step.**
+  (Do the class paths exist? Does the config parse? Are the class counts right?) List them as
+  gate/test items, not prose claims. This is the one SDD rung we keep.
+
+## 5. Handoff
+- List the tasks. Flag which are pattern-conforming vs not. Name the gates that must be green to merge.
+
+<!-- <<FILL: STACK-SPECIFIC SPEC SECTIONS>>  e.g. migration plan, API version bump, deploy steps. -->

okl/scaffold/claude/rules/example-area.md

@@ -0,0 +1,22 @@
+---
+description: Conventions for <AREA> — loaded only when the agent touches matching files.
+paths:
+  - "<<FILL: glob, e.g. **/*.sql or src/payments/**>>"
+---
+
+# <AREA> rules (path-scoped — surface 2, lazy-loaded)
+
+<!-- This is a TEMPLATE for a path-scoped rule file. Copy it per area, set `paths:`, keep it short.
+     The point of path-scoped rules is that CLAUDE.md stays lean: rules load into context ONLY when
+     the agent is working on files that match the glob. Target ~30–60 lines each.
+
+     Example (delete and replace):
+
+     # Database rules (paths: **/*.sql, **/migrations/**)
+     - Every migration is reversible; ship the down-migration in the same PR.
+     - No `SELECT *` in application queries; name columns so a schema change breaks loudly.
+     - Money is DECIMAL, never float; never round in the DB layer.
+-->
+
+- <<FILL: rule 1>>
+- <<FILL: rule 2>>

okl/scaffold/claude/skills/RECOMMENDED-COMPANIONS.md

@@ -0,0 +1,40 @@
+# Recommended companion skills (install separately)
+
+This kit ships two first-party skills — **`encoding-loop`** (turn a finding into a
+promoted, recorded rule) and **`verify-before-claiming`** (evidence before assertion).
+They are the two disciplines specific to this method.
+
+The broader engineering-discipline skills that pair well with it — systematic debugging,
+test-driven development, plan writing/execution, git-worktree isolation — are **not
+bundled here on purpose.** The best-maintained open versions live in third-party skill
+collections, and vendoring them would mean redistributing someone else's work (with its
+own license and attribution) and shipping cross-references to sibling skills this kit
+doesn't contain. Point at them instead of copying:
+
+## Superpowers (obra)
+
+A collection of Claude Code skills for disciplined agentic development. The skills below
+reference each other via the `superpowers:` namespace, so install the collection as a
+unit rather than cherry-picking files:
+
+- `systematic-debugging` — root-cause-before-symptom, pressure-resistant debugging
+- `test-driven-development` — red/green/refactor discipline
+- `writing-plans` / `executing-plans` — spec → reviewed multi-step execution
+- `using-git-worktrees` — isolated workspace per feature
+- `verification-before-completion` — the upstream cousin of this kit's `verify-before-claiming`
+
+Install: follow the Superpowers project's own instructions (it manages its own namespace
+and inter-skill references). Verify its license permits your use before redistributing it
+inside your own repo.
+
+## How they fit with this method
+
+- Use **`encoding-loop`** whenever any of the companion skills surfaces a durable lesson —
+  a debugging root cause, a test that should always exist, a plan step that must not be
+  skipped — and record it to the knowledge layer so the next task inherits it.
+- Use **`verify-before-claiming`** as the last step of any companion skill that ends in a
+  "done"/"passing"/"fixed" claim.
+
+Keeping the general skills external and the method skills first-party is deliberate: the
+kit stays cleanly installable and license-clean, and you always run the companions'
+latest upstream versions rather than a frozen copy that drifts.

okl/scaffold/claude/skills/encoding-loop/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: encoding-loop
+description: Use when you discover a rule, antipattern, or lesson worth keeping ("we should never write this again" / "we should always do this when") and need to encode it at the right surface and record it to the org knowledge layer. Fires on review findings, debugging discoveries, audits, and prior-art hits.
+---
+
+# Encoding loop — turn a finding into a durable, promoted rule
+
+A trigger surfaced a candidate rule. The response is always the same two moves.
+
+## 1. Pick the smallest sufficient surface (softest→strongest)
+
+| # | Surface | Use when |
+|---|---|---|
+| 1 | `docs/` + diagram | the *why* needs more than a line, or reviewers need a picture |
+| 2 | `CLAUDE.md` | every session needs it, always-on (keep it lean — prefer a rule file) |
+| 2 | `.claude/rules/<area>.md` with `paths:` glob | scoped to a file category (loads only in context) |
+| 3 | `.claude/skills/` or `.claude/commands/` | a multi-step procedure with real logic |
+| 4 | `.coderabbit.yaml` path_instructions / `architecture-reviewer` checklist | catch at PR-review time |
+| 5 | a gate in `gates/` + CI | mechanical, build-breaking — for rules that keep being broken |
+
+Default to the *softest* surface that could hold the rule. **Promote down (toward 5) only as it
+earns it** — a rule that keeps being violated moves to a sterner tier, not a sterner paragraph.
+Most rules never leave tier 1, and that is fine.
+
+## 2. Record it to the org layer so other repos inherit it
+
+```
+okl record --type <Defect|Gate|Rule|Claim|Retraction|Tombstone|Decision|PriorArt> \
+  --title "..." --body "..." --scope <org|repo> [--verified]
+```
+
+- **`scope=org`** — a fact about the world: prior art, an API contract, a data-source gotcha, a
+  portable gate. It will surface in every connected repo's `okl check`.
+- **`scope=repo`** — a quirk true only of this codebase. Stays local.
+
+If the finding retracts a prior claim, also add it to `registries/RETRACTIONS.md`; if it retires an
+identifier, add it to `registries/tombstones.txt`. The CI gates then fail any doc that contradicts.
+
+## 3. Verify the gate (if you made one)
+
+A gate you have only seen pass is a gate you have not tested. Run it against the real drifted file
+from git history and confirm it FAILS, then confirm it passes on the fix. Only then is it a gate.
+
+## Gotchas
+- A merged fix without the encoded rule is a half-finished job — the next instance slips through.
+- A surface nobody runs is documentation, not enforcement. If it is not read/executed, it will drift.
+- The drift you notice is the drift that embarrasses you; the flattering kind (stale "open" items)
+  needs a mechanical `verified_at`/TTL check, not vigilance.

okl/scaffold/claude/skills/verify-before-claiming/SKILL.md

@@ -0,0 +1,56 @@
+---
+name: verify-before-claiming
+description: Use before stating that work is done, a test passes, a build is green, a bug is fixed, a file exists, or any factual claim about the state of the code or the world. Requires running the check and reading its real output before asserting the result — evidence precedes assertion, always.
+---
+
+# Verify before claiming
+
+A claim about state — "the tests pass," "the file is created," "the endpoint returns
+404," "19 tests green" — is only worth as much as the check behind it. Stating a result
+you *expect* as if it were a result you *observed* is the single most common way
+AI-assisted work goes fast, fluent, plausible, and wrong.
+
+This skill has one rule: **run the check, read the output, then make the claim — in that
+order.** If you have not run the check this turn, you do not have the result; you have a
+guess. Say "I expect" for a guess and "I confirmed" only for an observation.
+
+## When this fires
+
+- About to write "done", "fixed", "passing", "green", "works", "created", "verified".
+- About to put a count, a status, or a value into prose, a commit message, a README, a
+  PR description, or a report.
+- About to tell a human that a thing is true about the code or the system.
+
+## The procedure
+
+1. **Name the check.** What single command or observation would make this claim true or
+   false? (`pytest -q`, `ls path`, `curl -s -o /dev/null -w '%{http_code}'`, `git status`.)
+2. **Run it this turn.** Not "I ran it earlier" — state drifts; a file moved, a kernel
+   reset, an install got lost. Re-run it now.
+3. **Read the real output.** The exit code and the actual lines — not the first line, not
+   what you assume follows.
+4. **Claim only what the output shows.** "18 passed, 1 skipped" — not "all green." If the
+   output surprises you, the output wins; investigate before you claim.
+5. **If you cannot run the check, say so.** "I could not run the suite in this
+   environment, so I have not confirmed the count" is a true statement. "Tests pass" when
+   you didn't run them is not.
+
+## Anti-patterns this exists to stop
+
+- **Reciting a remembered number.** "19 passing tests" carried from three turns ago, when
+  the suite was never run this session (or was, and now one fails). Re-run; report today's
+  result.
+- **Reporting the expected instead of the observed.** Writing the result the code *should*
+  produce as the result it *did* produce. These diverge exactly when it matters.
+- **"Ran it" ≠ "passed it".** A command that executed is not a command that succeeded.
+  Check the exit code, not just that it ran.
+- **Success by absence.** "No errors shown" is not "it worked" — a check that did not run
+  produces no errors either. Absence of a failure signal and presence of a success signal
+  are different things (see also: the knowledge layer's fail-closed rule).
+
+## The link to the rest of the method
+
+This is the personal-discipline version of what the mechanical gates enforce at CI time
+and what `okl check` enforces at task time: **a claim with no check behind it is
+documentation, not verification.** When a verification you skipped later turns into a
+defect, that defect is worth encoding (`okl record`) so the next task is warned.

okl/scaffold/evals/README.md

@@ -0,0 +1,32 @@
+# Evals — the measurement tier (surface 5, for behavior)
+
+The gates in `gates/` catch drift in *artifacts* (docs, identifiers, canon size). This tier catches
+drift in *behavior* — did the change make the system measurably worse? It is here because the RAG service's
+single most dangerous defect was a metric that could not report its own unreliability
+("LLM Judge 5.0/5.0 while 19 of 20 cases crashed").
+
+## The three rules this harness enforces (earned, not invented)
+
+1. **A metric that cannot report its own failure rate is not a metric.** `run_evals.py` leads with
+   its failure count and prints `❌ RESULTS NOT USABLE` above a configurable failure-rate threshold —
+   *before* any score. A green average over a crashed suite is the failure mode to prevent.
+2. **The judge must not grade its own homework.** If you use an LLM judge, it must be a different
+   model from the generator. The harness refuses to run if `JUDGE_MODEL == GENERATOR_MODEL`.
+3. **Bake in the error-analysis cross-tab.** Every eval run emits the `retrieval_hit × judge_score`
+   (or your task's equivalent `precondition × outcome`) cross-tab, because that 2×2 is the only thing
+   that told the RAG service which component was actually failing. It runs on every eval, not as a one-off.
+
+## Golden set from real failures — not invented fixtures
+
+Rule 4 of the method: *fixtures you invented cannot falsify assumptions you hold.* Seed `cases.jsonl`
+from real inputs that actually broke (the RAG service used its 25 real EDGAR filenames verbatim), not from
+hand-written happy-path examples.
+
+## Files
+- `run_evals.py` — the harness (framework-agnostic; adapt `evaluate_one()` to your system)
+- `cases.jsonl` — the golden set (`<<FILL>>` with real cases)
+- results write to `results/` with the failure count and cross-tab at the top
+
+## Wire into CI
+Add to `ci/` after the gates: a regression fails the build if the usable pass-rate drops below the
+committed baseline. Never quote a number from a run whose failure rate tripped `RESULTS NOT USABLE`.

okl/scaffold/evals/cases.jsonl

@@ -0,0 +1 @@
+{"id": "example-1", "input": "<<FILL: a real input that actually broke>>", "expected": "<<FILL: expected behavior>>"}

okl/scaffold/evals/run_evals.py

@@ -0,0 +1,109 @@
+#!/usr/bin/env python3
+"""Eval harness — measures behavior and, crucially, reports its own unreliability first.
+
+Framework-agnostic: plug your system into `evaluate_one()`. The invariants it enforces are the
+earned lessons, not any particular eval library (works alongside deepeval/ragas/promptfoo or none).
+
+Usage:  python run_evals.py [--cases cases.jsonl] [--fail-rate 0.20]
+Env:    GENERATOR_MODEL, JUDGE_MODEL  (must differ — rule: no grading your own homework)
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+from collections import Counter
+from datetime import datetime, timezone
+from pathlib import Path
+
+
+def evaluate_one(case: dict) -> dict:
+    """<<FILL>>: run YOUR system on `case` and return a result dict.
+
+    Required keys in the returned dict:
+      - "ok": bool            — did the case COMPLETE without crashing (not "did it pass")
+      - "score": float|None   — the judge/quality score, or None if it didn't complete
+      - "precondition": bool  — the x-axis of the cross-tab (e.g. retrieval_hit); task-specific
+      - "outcome_bad": bool   — the y-axis (e.g. answer judged bad)
+      - "error": str|None
+    Replace the stub below with a real call into your app.
+    """
+    # STUB — deterministic placeholder so the harness runs before you wire your system.
+    q = case.get("input", "")
+    return {"ok": True, "score": 5.0 if q else 0.0,
+            "precondition": bool(q), "outcome_bad": not bool(q), "error": None}
+
+
+def main(argv=None) -> int:
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--cases", default=str(Path(__file__).parent / "cases.jsonl"))
+    ap.add_argument("--fail-rate", type=float, default=0.20,
+                    help="usable-results threshold; above this, results are NOT USABLE")
+    args = ap.parse_args(argv)
+
+    # Rule 2: the judge must not be the generator.
+    gen, judge = os.environ.get("GENERATOR_MODEL"), os.environ.get("JUDGE_MODEL")
+    if gen and judge and gen == judge:
+        print(f"❌ REFUSING TO RUN: judge model == generator model ({gen}). "
+              "A model grading its own output is a mirror, not a signal.", file=sys.stderr)
+        return 3
+
+    path = Path(args.cases)
+    if not path.exists():
+        print(f"no cases file at {path} — add a golden set (see README). Nothing to measure.")
+        return 0
+    cases = [json.loads(line) for line in path.read_text().splitlines() if line.strip()]
+    if not cases:
+        print("cases.jsonl is empty — add real failing cases before trusting any number.")
+        return 0
+
+    results = []
+    for c in cases:
+        try:
+            r = evaluate_one(c)
+        except Exception as e:  # a crash is a completed-with-failure, counted as such
+            r = {"ok": False, "score": None, "precondition": False, "outcome_bad": True, "error": repr(e)}
+        results.append(r)
+
+    n = len(results)
+    crashed = [r for r in results if not r.get("ok")]
+    fail_rate = len(crashed) / n
+
+    # ---- Rule 1: LEAD with the failure count, before any score. ----
+    print("=" * 60)
+    print(f"EVAL RUN {datetime.now(timezone.utc).isoformat()}")
+    print(f"cases: {n} | completed: {n - len(crashed)} | crashed: {len(crashed)} "
+          f"| failure-rate: {fail_rate:.0%}")
+    usable = fail_rate <= args.fail_rate
+    if not usable:
+        print(f"❌ RESULTS NOT USABLE — failure rate {fail_rate:.0%} exceeds {args.fail_rate:.0%}. "
+              "Do not quote any score below.")
+    completed = [r for r in results if r.get("ok") and r.get("score") is not None]
+    if completed:
+        avg = sum(r["score"] for r in completed) / len(completed)
+        label = "avg score (COMPLETED ONLY — not the whole suite)" if not usable else "avg score"
+        print(f"{label}: {avg:.2f}  over {len(completed)} completed case(s)")
+
+    # ---- Rule 3: the error-analysis cross-tab, every run. ----
+    print("\nerror-analysis cross-tab (precondition × outcome):")
+    ct = Counter((r.get("precondition", False), not r.get("outcome_bad", True)) for r in results)
+    print("                 outcome GOOD   outcome BAD")
+    print(f"  precond OK   :   {ct[(True, True)]:>6}       {ct[(True, False)]:>6}")
+    print(f"  precond MISS :   {ct[(False, True)]:>6}       {ct[(False, False)]:>6}")
+    print("  (if BAD concentrates in precond-OK, the downstream stage is the problem, not the precondition.)")
+
+    # write results
+    outdir = Path(__file__).parent / "results"
+    outdir.mkdir(exist_ok=True)
+    stamp = datetime.now(timezone.utc).strftime("%Y%m%dT%H%M%SZ")
+    (outdir / f"eval-{stamp}.json").write_text(json.dumps(
+        {"n": n, "failure_rate": fail_rate, "usable": usable, "results": results}, indent=2))
+    print(f"\nwrote results/eval-{stamp}.json")
+
+    # CI semantics: non-zero if results are not usable (blocks quoting a bogus number)
+    return 0 if usable else 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

okl/scaffold/gates/check-canon-size.sh

@@ -0,0 +1,11 @@
+#!/usr/bin/env bash
+# Warn/fail on CLAUDE.md size (keep the canon lean; detail belongs in rules/skills/docs).
+set -uo pipefail
+cd "$(dirname "$0")/.."
+[ -f CLAUDE.md ] || { echo "no CLAUDE.md — skipping"; exit 0; }
+WARN="${CANON_WARN:-200}"; FAIL="${CANON_FAIL:-300}"
+n=$(wc -l < CLAUDE.md)
+if [ "$n" -gt "$FAIL" ]; then echo "  ✗ CLAUDE.md is $n lines (> $FAIL). Split into .claude/rules/*.md."; exit 1; fi
+if [ "$n" -gt "$WARN" ]; then echo "  ⚠ CLAUDE.md is $n lines (> $WARN soft budget). Consider splitting."; fi
+echo "   CLAUDE.md: $n lines"
+exit 0

okl/scaffold/gates/check-doc-orphans.sh

@@ -0,0 +1,19 @@
+#!/usr/bin/env bash
+# Fail if a doc under docs/ is not reachable (linked) from a hub file or another doc.
+# A doc nobody links to drifts unseen — this is the doc-orphan reachability gate.
+set -uo pipefail
+cd "$(dirname "$0")/.."
+[ -d docs ] || { echo "no docs/ — skipping"; exit 0; }
+HUBS="$(ls docs/README.md docs/index.md CLAUDE.md METHOD.md 2>/dev/null || true)"
+[ -z "$HUBS" ] && { echo "no hub file — skipping"; exit 0; }
+rc=0
+for doc in docs/*.md; do
+  [ -e "$doc" ] || continue
+  base="$(basename "$doc")"
+  # skip hub files and kit-shipped reference docs (not project docs to link)
+  case "$base" in README.md|index.md|method-kit-manifest.md) continue;; esac
+  if ! grep -RqlF "$base" $HUBS docs/ --include='*.md' 2>/dev/null; then
+    echo "  ✗ orphan doc (unlinked from any hub or sibling): $doc"; rc=1
+  fi
+done
+exit $rc

okl/scaffold/gates/check-retractions.sh

@@ -0,0 +1,22 @@
+#!/usr/bin/env bash
+# Fail if a tracked doc restates a retracted claim without retracting it.
+# Each retraction entry declares a quoted claim; if that exact quote appears in a doc OTHER than the
+# retraction registry, flag it. (A restated claim needs its own retraction note or removal.)
+set -uo pipefail
+cd "$(dirname "$0")/.."
+REG="registries/RETRACTIONS.md"
+[ -f "$REG" ] || { echo "no RETRACTIONS.md — skipping"; exit 0; }
+rc=0
+tmp="$(mktemp)"
+grep -oE '"[^"]{12,}"' "$REG" | sed 's/^"//;s/"$//' > "$tmp" || true
+while IFS= read -r claim; do
+  [ -z "$claim" ] && continue
+  hits="$(grep -RnF "$claim" . --include='*.md' 2>/dev/null | grep -v "$REG" || true)"
+  if [ -n "$hits" ]; then
+    echo "  ✗ retracted claim restated: \"$claim\""
+    echo "$hits" | sed 's/^/      /'
+    rc=1
+  fi
+done < "$tmp"
+rm -f "$tmp"
+exit $rc

okl/scaffold/gates/check-tombstones.sh

@@ -0,0 +1,22 @@
+#!/usr/bin/env bash
+# Fail if a retired identifier (tombstones.txt) reappears in tracked source/docs/config.
+set -uo pipefail
+cd "$(dirname "$0")/.."
+TS="registries/tombstones.txt"
+[ -f "$TS" ] || { echo "no tombstones.txt — skipping"; exit 0; }
+rc=0
+while IFS= read -r line; do
+  case "$line" in ''|'#'*) continue;; esac
+  id="$(printf '%s' "$line" | cut -f1)"
+  [ -z "$id" ] && continue
+  hits="$(grep -RnF "$id" . \
+          --include='*.md' --include='*.py' --include='*.ts' --include='*.tsx' \
+          --include='*.cs' --include='*.yaml' --include='*.yml' --include='*.json' --include='*.sh' \
+          2>/dev/null | grep -v 'registries/' || true)"
+  if [ -n "$hits" ]; then
+    echo "  ✗ tombstoned identifier '$id' resurrected:"
+    echo "$hits" | sed 's/^/      /'
+    rc=1
+  fi
+done < "$TS"
+exit $rc

okl/scaffold/gates/run-gates.sh

@@ -0,0 +1,31 @@
+#!/usr/bin/env bash
+# run-gates.sh — the mechanical drift-gates (surface 5). Portable; stack-agnostic.
+# Run locally via `/check-rules` or `bash gates/run-gates.sh`; wired into CI (see ci/).
+#
+# Each gate is a separate script returning non-zero on drift. This runner aggregates them so one
+# red gate fails the whole check (fail-closed). Add stack-specific gates in the <<FILL>> block.
+set -uo pipefail
+cd "$(dirname "$0")/.."   # repo root
+GATES_DIR="gates"
+fail=0
+
+run() {
+  local name="$1"; shift
+  echo "── gate: $name ──"
+  if "$@"; then echo "   ✓ $name"; else echo "   ✗ $name FAILED"; fail=1; fi
+}
+
+run "retractions"     bash "$GATES_DIR/check-retractions.sh"
+run "tombstones"      bash "$GATES_DIR/check-tombstones.sh"
+run "doc-orphans"     bash "$GATES_DIR/check-doc-orphans.sh"
+run "canon-size"      bash "$GATES_DIR/check-canon-size.sh"
+
+# <<FILL: STACK-SPECIFIC GATES — e.g. class-path import check, analyzer, type-check, tests>>
+# run "class-paths"   bash "$GATES_DIR/check-scaffold-classpaths.sh"
+# run "tests"         your-test-command
+
+if [ "$fail" -ne 0 ]; then
+  echo; echo "GATES RED — do not merge. Encode the fix at the smallest surface, then re-run."
+  exit 1
+fi
+echo; echo "All gates green."

okl/scaffold/hooks/hooks.json

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