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

okl/client.py

@@ -0,0 +1,160 @@
+"""Client resolution: talk to a REMOTE service if configured, else a LOCAL store.
+
+`okl connect <url>` writes the service URL into .okl/config.json. When a remote
+is configured every operation is an HTTP call; otherwise it falls back to a
+local store file (single-machine mode). This is what lets the same CLI work
+before you've deployed the shared service and after.
+"""
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+from typing import Any
+from urllib import request as _req
+from urllib.error import HTTPError, URLError
+
+from . import core
+from .store import Store
+
+CONFIG_DIR = ".okl"
+CONFIG_FILE = "config.json"
+
+
+def _find_config(start: Path | None = None) -> Path | None:
+    p = (start or Path.cwd()).resolve()
+    for d in [p, *p.parents]:
+        cfg = d / CONFIG_DIR / CONFIG_FILE
+        if cfg.exists():
+            return cfg
+    return None
+
+
+def load_config() -> dict[str, Any]:
+    cfg = _find_config()
+    if cfg:
+        return json.loads(cfg.read_text())
+    return {}
+
+
+def save_config(data: dict[str, Any], root: Path | None = None) -> Path:
+    d = (root or Path.cwd()) / CONFIG_DIR
+    d.mkdir(parents=True, exist_ok=True)
+    path = d / CONFIG_FILE
+    path.write_text(json.dumps(data, indent=2) + "\n")
+    return path
+
+
+class Client:
+    """Uniform surface over local-store and remote-service modes."""
+
+    def __init__(self, config: dict[str, Any] | None = None):
+        self.config = config if config is not None else load_config()
+        self.service_url = os.environ.get("OKL_SERVICE_URL") or self.config.get("service_url")
+        self.repo = self.config.get("repo") or Path.cwd().name
+        self.interests = self.config.get("interests") or []
+        self._store: Store | None = None
+
+    @property
+    def mode(self) -> str:
+        return "remote" if self.service_url else "local"
+
+    def _local_store(self) -> Store:
+        if self._store is None:
+            # local store lives next to the config, or ./okl.db
+            cfg = _find_config()
+            db = (cfg.parent / "okl.db") if cfg else Path("okl.db")
+            self._store = Store(f"sqlite:///{db}")
+        return self._store
+
+    # -- HTTP helper (stdlib only; fails CLOSED — raises, never returns empty) --
+    def _post(self, path: str, payload: dict) -> dict:
+        url = self.service_url.rstrip("/") + path
+        data = json.dumps(payload).encode()
+        req = _req.Request(url, data=data, headers={"Content-Type": "application/json"})
+        token = os.environ.get("OKL_TOKEN") or self.config.get("token")
+        if token:
+            req.add_header("Authorization", f"Bearer {token}")
+        try:
+            with _req.urlopen(req, timeout=10) as resp:
+                return json.loads(resp.read())
+        except HTTPError as e:
+            # The service answered — so this is NOT "unreachable". A 4xx is the caller's
+            # error and must surface its detail (found by E2E: an unknown-tag 400 was
+            # reported to the agent as an outage).
+            try:
+                detail = json.loads(e.read()).get("detail", "")
+            except Exception:  # noqa: BLE001
+                detail = ""
+            if 400 <= e.code < 500:
+                raise ValueError(f"OKL service rejected the request ({e.code}): {detail or e.reason}") from e
+            raise OKLUnreachable(f"OKL service error at {url}: {e.code} {detail or e.reason}") from e
+        except URLError as e:
+            raise OKLUnreachable(f"OKL service unreachable at {url}: {e}") from e
+
+    # -- operations ---------------------------------------------------------
+    def check(self, task: str, repo: str | None = None) -> dict:
+        repo = repo or self.repo
+        if self.mode == "remote":
+            return self._post("/check", {"repo": repo, "task": task,
+                                         "interests": self.interests or None})
+        return core.check(self._local_store(), repo, task, interests=self.interests)
+
+    def record(self, **kwargs) -> str:
+        # Default the repo in BOTH modes: `--scope repo` needs it to become repo:<name>,
+        # and the remote path used to skip this (found by E2E: 400 on every repo-scoped record).
+        kwargs.setdefault("repo", self.repo)
+        if self.mode == "remote":
+            return self._post("/record", kwargs)["id"]
+        return core.record(self._local_store(), **kwargs)
+
+    def search(self, query: str, scope: str | None = None,
+               node_types: list[str] | None = None, limit: int = 25) -> list[dict]:
+        if self.mode == "remote":
+            return self._post("/search", {"query": query, "scope": scope,
+                                          "node_types": node_types, "limit": limit})["results"]
+        return core.search(self._local_store(), query, scope, node_types, limit)
+
+    def link(self, src: str, rel: str, dst: str) -> None:
+        if self.mode == "remote":
+            self._post("/link", {"src": src, "rel": rel, "dst": dst})
+            return
+        core.link(self._local_store(), src, rel, dst)
+
+    def verify(self, node_id: str, evidence: str) -> dict:
+        if self.mode == "remote":
+            return self._post("/verify", {"id": node_id, "evidence": evidence})
+        return core.verify(self._local_store(), node_id, evidence)
+
+    def recurrence(self) -> list[dict]:
+        if self.mode == "remote":
+            return self._get("/metric/recurrence")["recurrence_after_arming"]
+        return self._local_store().recurrence_after_arming()
+
+    def all_nodes(self):
+        """Return all in-scope Node objects (local store, or /nodes on a remote service).
+
+        Used by the drift detector, which needs the node set locally but runs its
+        git lookups against the working tree.
+        """
+        from .store import Node
+        if self.mode == "remote":
+            rows = self._get("/nodes")["nodes"]
+            return [Node(**{k: v for k, v in r.items()
+                            if k in Node.__dataclass_fields__}) for r in rows]
+        return self._local_store().all_nodes()
+
+    def _get(self, path: str) -> dict:
+        url = self.service_url.rstrip("/") + path
+        try:
+            with _req.urlopen(url, timeout=10) as resp:
+                return json.loads(resp.read())
+        except URLError as e:
+            raise OKLUnreachable(f"OKL service unreachable at {url}: {e}") from e
+
+
+class OKLUnreachable(RuntimeError):
+    """Raised when a configured remote service can't be reached. Callers that
+    gate work on OKL (the pre-task hook) must FAIL CLOSED on this — the
+    merge-gate lesson: a check that silently returns 'nothing' is worse than
+    no check."""

okl/core.py

@@ -0,0 +1,223 @@
+"""The three operations, independent of transport (CLI / HTTP / MCP all call these).
+
+check(repo, task)   -> the pre-task neighborhood: armed gates, live retractions,
+                       in-scope tombstones, THREAT prior-art, vocabulary, stale warnings.
+                       This is the load-bearing read (design doc §3.4). Fails CLOSED
+                       at the transport layer, never here.
+record(node, scope) -> the org-scope arm of the encoding response (§3.3).
+search(query, ...)  -> targeted retrieval (progressive disclosure).
+"""
+from __future__ import annotations
+
+from dataclasses import asdict
+from typing import Any
+
+from .store import Edge, Node, Store, _now_ms, split_tags
+
+
+def _node_public(n: Node) -> dict[str, Any]:
+    d = asdict(n)
+    d["stale"] = n.is_stale()
+    return d
+
+
+def _in_scope(n: Node, repo_scope: str, interests: list[str] | None) -> bool:
+    """Scope answers "who may see this"; tags answer "what is this about".
+    The repo's own nodes and untagged nodes always pass — declared interests
+    only drop org nodes tagged entirely outside them."""
+    if n.scope == repo_scope:
+        return True
+    if n.scope != "org":
+        return False
+    if not interests:
+        return True
+    tags = split_tags(n.tags)
+    return not tags or bool(tags & {t.strip().lower() for t in interests if t.strip()})
+
+
+def check(store: Store, repo: str, task: str, limit: int = 12,
+          interests: list[str] | None = None) -> dict[str, Any]:
+    """Return the slice of the encoded body relevant to starting `task` in `repo`.
+
+    Matches on the task text across all node types, then buckets by type so the
+    agent gets an actionable briefing rather than a flat list. Org-scope nodes
+    and this repo's own nodes are both in scope; other repos' repo-scope nodes
+    are not (that is the curation boundary, §"repo vs org scope").
+
+    `interests` is the repo's declared subject-tag list (.okl/config.json). When
+    set, org-scope nodes tagged entirely OUTSIDE it are dropped: scope answers
+    "who may see this", tags answer "what is this about". Untagged nodes and the
+    repo's own nodes always pass — declaring interests must never hide them.
+    """
+    repo_scope = f"repo:{repo}"
+    hits = [n for n in store.search(task, limit=limit * 3)
+            if _in_scope(n, repo_scope, interests)]
+
+    buckets: dict[str, list[dict]] = {
+        "armed_gates": [], "relevant_defects": [], "live_retractions": [],
+        "in_scope_tombstones": [], "threat_prior_art": [], "rules": [],
+        "vocabulary": [], "stale_warnings": [],
+    }
+    for n in hits:
+        pub = _node_public(n)
+        if n.is_stale():
+            buckets["stale_warnings"].append(pub)
+        if n.type == "Gate":
+            buckets["armed_gates"].append(pub)
+        elif n.type == "Defect":
+            buckets["relevant_defects"].append(pub)
+        elif n.type == "Retraction" or (n.type == "Claim" and n.status == "retracted"):
+            buckets["live_retractions"].append(pub)
+        elif n.type == "Tombstone":
+            buckets["in_scope_tombstones"].append(pub)
+        elif n.type == "PriorArt" and (n.status == "live" or (n.body and "THREAT" in n.body)):
+            buckets["threat_prior_art"].append(pub)
+        elif n.type == "Rule":
+            buckets["rules"].append(pub)
+        elif n.type == "Vocabulary":
+            buckets["vocabulary"].append(pub)
+
+    # For each armed gate, pull the defect it CATCHES so the briefing says *why*.
+    for g in buckets["armed_gates"]:
+        why = {n.title for (e, n) in store.neighbors(g["id"], rels=["CATCHES"])
+               if n.type == "Defect"}
+        g["catches"] = sorted(why)
+
+    # Router (Codified Context §3.1.1 `suggest_agent`): turn the matched nodes into an
+    # explicit, ordered action list so the agent gets "do this" not just "here's context".
+    actions: list[dict] = []
+    for g in buckets["armed_gates"]:
+        actions.append({"kind": "arm_gate", "target": g["title"],
+                        "why": g.get("catches") or None,
+                        "how": g.get("fix") or "run this gate before you finish the task"})
+    for d in buckets["relevant_defects"] + buckets["rules"]:
+        if d.get("fix"):
+            actions.append({"kind": "apply_fix", "target": d["title"],
+                            "symptom": d.get("symptom"), "how": d["fix"]})
+    for r in buckets["live_retractions"]:
+        actions.append({"kind": "avoid_retracted", "target": r["title"],
+                        "how": "do not restate this as fact; it was retracted"})
+    for t in buckets["in_scope_tombstones"]:
+        actions.append({"kind": "avoid_identifier", "target": t["title"],
+                        "how": "do not reintroduce this retired identifier"})
+
+    total = sum(len(v) for k, v in buckets.items() if k != "stale_warnings")
+    return {"repo": repo, "task": task, "match_count": total,
+            "next_actions": actions, **buckets}
+
+
+def record(store: Store, *, type: str, title: str, scope: str, repo: str | None = None,
+           body: str | None = None, status: str | None = None, found_by: str | None = None,
+           ttl_days: int | None = None, owner: str | None = None,
+           files: str | None = None, symptom: str | None = None, fix: str | None = None,
+           tags: str | None = None, verified: bool = False, id: str | None = None) -> str:
+    """Create a node. `scope` is 'org' (propagates to all repos) or 'repo:<name>'.
+
+    The scope decision is the curation gate: only world-facts (prior art, API
+    contracts, data-source gotchas, vocabulary) should be 'org'. Repo-specific
+    quirks stay 'repo:<name>' and never leak into another repo's `check`.
+
+    `files` is a comma-separated list of path globs the node governs; setting it
+    enrolls the node in the source-vs-spec drift detector (see drift.py).
+    `symptom`/`fix` populate the Symptom→Cause→Fix schema (cause lives in `body`)
+    so `check` can surface "if you see X, it's Y, do Z" instead of prose.
+    `tags` is a comma-separated subject list from the controlled vocabulary
+    (store.KNOWN_TAGS); repos declare interest tags so `check` can filter by subject.
+    """
+    if scope == "repo" and repo:
+        scope = f"repo:{repo}"
+    kw = dict(
+        type=type, title=title, scope=scope, repo=repo, body=body, status=status,
+        found_by=found_by, ttl_days=ttl_days, owner=owner,
+        files=files, symptom=symptom, fix=fix, tags=tags,
+        verified_at=_now_ms() if verified else None,
+    )
+    # An explicit id makes the write idempotent (upsert replaces the same row);
+    # omit it and the store mints a fresh random id (a genuinely new node).
+    if id is not None:
+        kw["id"] = id
+    n = Node(**kw)
+    return store.add_node(n)
+
+
+def link(store: Store, src: str, rel: str, dst: str) -> None:
+    store.add_edge(Edge(src=src, rel=rel, dst=dst))
+
+
+def verify(store: Store, node_id: str, evidence: str) -> dict[str, Any]:
+    """Stamp a node verified from an OBSERVED check — never from assertion.
+
+    `evidence` names the check that passed (the command + when). This is the
+    store-side half of the verify-before-claiming rule: callers (the CLI, CI)
+    must actually run the check first; this function just refuses to stamp
+    without an evidence string and records it as the audit trail.
+    """
+    if not evidence or not evidence.strip():
+        raise ValueError("refusing to stamp verification without evidence — run a check and pass it")
+    n = store.get_node(node_id)
+    if n is None:
+        raise ValueError(f"no node with id {node_id!r}")
+    n.verified_at = _now_ms()
+    n.verified_by = evidence.strip()
+    store.add_node(n)
+    return _node_public(n)
+
+
+def search(store: Store, query: str, scope: str | None = None,
+           node_types: list[str] | None = None, limit: int = 25) -> list[dict]:
+    return [_node_public(n) for n in store.search(query, scope, node_types, limit)]
+
+
+def render_check_for_agent(result: dict[str, Any]) -> str:
+    """Format a check() result as compact markdown for injection into agent context."""
+    lines = [f"## OKL briefing — {result['repo']} · task: {result['task']}",
+             f"_{result['match_count']} relevant node(s) from the org's encoded body._", ""]
+
+    # Router first: the ordered "do this" list, so the agent acts, not just reads.
+    actions = result.get("next_actions") or []
+    if actions:
+        lines.append("### ✅ Do this (routed actions)")
+        verb = {"arm_gate": "ARM", "apply_fix": "FIX", "avoid_retracted": "AVOID",
+                "avoid_identifier": "AVOID"}
+        for a in actions:
+            v = verb.get(a["kind"], "DO")
+            sym = f" — when you see: {a['symptom']}" if a.get("symptom") else ""
+            lines.append(f"- **{v}: {a['target']}**{sym}")
+            lines.append(f"    → {a['how']}")
+        lines.append("")
+
+    order = [
+        ("armed_gates", "🔒 Armed gates — adopt before you start"),
+        ("relevant_defects", "⚠️  Past defects in this area"),
+        ("live_retractions", "🚫 Live retractions — do not restate as fact"),
+        ("in_scope_tombstones", "⛔ Retired identifiers — do not resurrect"),
+        ("threat_prior_art", "📄 Prior art (THREAT) — novelty already claimed"),
+        ("rules", "📐 Encoded rules"),
+        ("vocabulary", "📖 Vocabulary"),
+    ]
+    any_hit = False
+    for key, header in order:
+        items = result.get(key) or []
+        if not items:
+            continue
+        any_hit = True
+        lines.append(f"### {header}")
+        for it in items:
+            suffix = ""
+            if key == "armed_gates" and it.get("catches"):
+                suffix = f"  ← catches: {', '.join(it['catches'])}"
+            tag = " *(STALE — re-verify)*" if it.get("stale") else ""
+            lines.append(f"- **{it['title']}**{tag}{suffix}")
+            if it.get("symptom"):
+                lines.append(f"  symptom: {it['symptom'][:160]}")
+            if it.get("body"):
+                lines.append(f"  cause: {it['body'][:200]}" if it.get("symptom") else f"  {it['body'][:200]}")
+            if it.get("fix"):
+                lines.append(f"  fix: {it['fix'][:200]}")
+        lines.append("")
+    if result.get("stale_warnings"):
+        lines.append(f"> {len(result['stale_warnings'])} node(s) are past TTL and shown demoted — re-verify before trusting.")
+    if not any_hit:
+        lines.append("_No encoded lessons matched this task. Proceeding with a clean slate — "
+                     "record anything you learn with `okl record`._")
+    return "\n".join(lines)

okl/drift.py

@@ -0,0 +1,119 @@
+"""Source-vs-spec drift detection.
+
+The problem (Codified Context, arXiv 2602.20478 §5.2 — their *primary* failure mode):
+an encoded rule points at code, the code changes, the rule is never revisited, and the
+agent is now primed with a stale mental model. OKL already catches two drift classes —
+doc-orphans (a doc nobody links) and resurrected tombstones (a retired id reused) — but
+nothing catches "the code this rule governs moved after the rule was last verified."
+
+This closes that gap. A node may declare `files` (comma-separated path globs it governs).
+For each such node we ask git for the last commit that touched any matching path; if that
+commit is newer than the node's `verified_at` (or the node was never verified), the node
+has *drifted* — its source changed under it and a human should re-verify it.
+
+Unlike the passive TTL clock (store.Node.is_stale), this is event-driven: it fires exactly
+when the governed code moves, not on a fixed schedule.
+"""
+from __future__ import annotations
+
+import subprocess
+from collections.abc import Iterable
+from dataclasses import dataclass
+from typing import Any
+
+from .store import Node
+
+
+@dataclass
+class DriftHit:
+    node_id: str
+    title: str
+    scope: str
+    files: str
+    last_change_ms: int          # newest governed-file commit, epoch ms
+    verified_at: int | None      # node's last verification, epoch ms (None = never)
+    reason: str
+
+    def as_dict(self) -> dict[str, Any]:
+        return {
+            "node_id": self.node_id, "title": self.title, "scope": self.scope,
+            "files": self.files, "last_change_ms": self.last_change_ms,
+            "verified_at": self.verified_at, "reason": self.reason,
+        }
+
+
+def _git_last_change_ms(globs: list[str], repo_dir: str) -> int | None:
+    """Epoch-ms of the most recent commit touching any path matching `globs`.
+
+    Uses `git log -1 --format=%ct -- <pathspec...>`. Returns None if git is
+    unavailable, the dir isn't a repo, or no commit ever touched those paths.
+    """
+    pathspecs = [g.strip() for g in globs if g.strip()]
+    if not pathspecs:
+        return None
+    try:
+        out = subprocess.run(
+            ["git", "-C", repo_dir, "log", "-1", "--format=%ct", "--", *pathspecs],
+            capture_output=True, text=True, timeout=15,
+        )
+    except (FileNotFoundError, subprocess.TimeoutExpired):
+        return None
+    if out.returncode != 0:
+        return None
+    ts = out.stdout.strip()
+    if not ts:
+        return None
+    try:
+        return int(ts) * 1000  # git %ct is epoch *seconds*
+    except ValueError:
+        return None
+
+
+def detect_drift(nodes: Iterable[Node], repo: str, repo_dir: str = ".") -> list[DriftHit]:
+    """Return nodes whose governed source changed after they were last verified.
+
+    `nodes` is any iterable of Node (Client.all_nodes() in local OR remote mode) —
+    drift is mode-agnostic on the node side; only the git lookup is local to `repo_dir`.
+    In scope: org nodes and this repo's own nodes (the same curation boundary as check()).
+    Only nodes with a non-empty `files` glob list participate.
+    """
+    repo_scope = f"repo:{repo}"
+    hits: list[DriftHit] = []
+    for n in nodes:
+        if not (n.scope == "org" or n.scope == repo_scope):
+            continue
+        if not n.files:
+            continue
+        globs = [g for g in n.files.split(",") if g.strip()]
+        last = _git_last_change_ms(globs, repo_dir)
+        if last is None:
+            continue  # git couldn't attribute a change — not evidence of drift
+        base = n.verified_at
+        if base is None:
+            hits.append(DriftHit(
+                n.id, n.title, n.scope, n.files, last, None,
+                "governed source has commits but the rule was never verified",
+            ))
+        elif last > base:
+            hits.append(DriftHit(
+                n.id, n.title, n.scope, n.files, last, base,
+                "governed source changed after the rule was last verified",
+            ))
+    return hits
+
+
+def render_drift(hits: list[DriftHit]) -> str:
+    if not hits:
+        return "OKL drift: OK — no encoded rule's governed source changed after its last verification."
+    lines = [f"OKL drift: {len(hits)} rule(s) may be stale (source changed after verification):", ""]
+    import datetime as _dt
+    for h in hits:
+        when = _dt.datetime.utcfromtimestamp(h.last_change_ms / 1000).strftime("%Y-%m-%d")
+        ver = ("never verified" if h.verified_at is None
+               else "verified " + _dt.datetime.utcfromtimestamp(h.verified_at / 1000).strftime("%Y-%m-%d"))
+        lines.append(f"  • [{h.node_id}] {h.title}")
+        lines.append(f"      files: {h.files}")
+        lines.append(f"      last source change: {when} · {ver} → {h.reason}")
+        lines.append("      fix: re-verify against current source, then `okl record --verified` to reset, "
+                     "or update the rule.")
+    return "\n".join(lines)

okl/mcp_server.py

@@ -0,0 +1,75 @@
+"""MCP server exposing okl.check / okl.record / okl.search to coding agents.
+
+This is how Claude Code / Cursor / Copilot call the layer as first-class tools.
+It resolves through the same Client, so it works in local OR remote mode. The
+check tool fails CLOSED (raises) if a configured remote is unreachable.
+
+Requires the `mcp` package: install okl[mcp]. Run: `okl mcp` (stdio transport).
+"""
+from __future__ import annotations
+
+from . import core
+from .client import Client, OKLUnreachable
+
+
+def _build():
+    try:
+        from mcp.server.fastmcp import FastMCP
+    except ImportError as e:  # pragma: no cover
+        raise RuntimeError("The MCP server needs the 'mcp' package — install okl[mcp]") from e
+
+    mcp = FastMCP("okl")
+    client = Client()
+
+    @mcp.tool()
+    def okl_check(task: str, repo: str | None = None) -> str:
+        """Read the org's relevant encoded lessons BEFORE starting a task.
+
+        Returns armed gates (with the defect each catches), past defects in this
+        area, live retractions, retired identifiers, THREAT prior-art, rules, and
+        vocabulary — as markdown to read before writing any code. Call this first.
+        """
+        try:
+            result = client.check(task, repo=repo)
+        except OKLUnreachable as e:
+            return (f"⚠️ OKL UNREACHABLE — cannot confirm a clean check ({e}). "
+                    "Treat as: lessons may exist that you cannot see. Proceed with caution "
+                    "and re-run once connectivity is restored.")
+        return core.render_check_for_agent(result)
+
+    @mcp.tool()
+    def okl_record(type: str, title: str, scope: str, body: str | None = None,
+                   status: str | None = None, found_by: str | None = None,
+                   ttl_days: int | None = None, repo: str | None = None,
+                   symptom: str | None = None, fix: str | None = None,
+                   files: str | None = None, tags: str | None = None) -> str:
+        """Record a lesson so other repos inherit it.
+
+        scope='org' for facts about the world (prior art, API contracts, data
+        gotchas, vocabulary) that should propagate to every repo; scope='repo'
+        for a quirk true only of this codebase. type is one of: Defect, Gate,
+        Rule, Claim, Retraction, Tombstone, Decision, PriorArt, Vocabulary, Entity.
+        symptom/fix make the lesson actionable ("when you see X → do Z"; cause
+        goes in body). files (comma-sep globs) enrolls it in drift detection.
+        tags (comma-sep, controlled vocabulary — e.g. react, security,
+        eval-integrity) categorize the subject so `check` can filter by interest.
+        """
+        node_id = client.record(type=type, title=title, scope=scope, body=body,
+                                 status=status, found_by=found_by, ttl_days=ttl_days, repo=repo,
+                                 symptom=symptom, fix=fix, files=files, tags=tags)
+        return f"recorded {node_id} ({type}, {scope})"
+
+    @mcp.tool()
+    def okl_search(query: str, scope: str | None = None, limit: int = 15) -> str:
+        """Search the org's encoded body for anything matching `query`."""
+        rows = client.search(query, scope=scope, limit=limit)
+        if not rows:
+            return "no matches."
+        return "\n".join(f"[{r['type']}] {r['scope']} — {r['title']}"
+                         + (" (STALE)" if r.get("stale") else "") for r in rows)
+
+    return mcp
+
+
+def run_stdio() -> None:
+    _build().run()

okl/scaffold/MANIFEST.md

@@ -0,0 +1,59 @@
+# Method kit — what's portable, what you fill
+
+`okl scaffold` stamps this tree into a repo. Everything here is **portable skeleton** — it works in
+any language/stack. The parts you complete per repo are marked inline with `<<FILL: ...>>`.
+
+## What gets installed where
+
+| Template (in package) | Installed to | Portable? |
+|---|---|---|
+| `root/CLAUDE.md` | `CLAUDE.md` | skeleton + FILL slots for stack rules |
+| `root/METHOD.md` | `METHOD.md` | fully portable (the seven earned rules) |
+| `claude/skills/encoding-loop/` | `.claude/skills/encoding-loop/` | fully portable |
+| `claude/agents/architecture-reviewer.md` | `.claude/agents/` | skeleton + FILL for stack checks |
+| `claude/commands/feature-spec.md`, `check-rules.md` | `.claude/commands/` | portable |
+| `claude/rules/example-area.md` | `.claude/rules/` | template — copy per area, set `paths:` |
+| `gates/*.sh` | `gates/` | fully portable (retractions/tombstones/orphans/canon-size) |
+| `registries/*` | `registries/` | portable format; FILL entries as earned |
+| `evals/*` | `evals/` | portable harness; FILL `evaluate_one()` + `cases.jsonl` |
+| `ci/method-gates.yml` | `.github/workflows/` | portable |
+| `hooks/*` | `.claude/hooks/` (+ plugin) | portable (fail-closed pre-task check) |
+| `plugin/plugin.json` | repo root (if `--plugin`) | portable — makes the whole thing a Claude Code plugin |
+
+## The portable / stack-specific boundary (the load-bearing decision)
+
+- **Portable (ships as-is):** the encoding loop, the six surfaces, the seven earned rules, the
+  drift-gate *scripts*, the eval *invariants* (failure-count-first, no self-grading judge, cross-tab),
+  the fail-closed pre-task hook, the registries *format*.
+- **Stack-specific (you fill):** the actual coding rules that make an agent code *your* way — framework
+  choices, domain constraints, pipeline conventions. These go in `.claude/rules/<area>.md` (with a
+  `paths:` glob) and the `<<FILL>>` slots, and are recorded to okl at `--scope repo` so they never
+  leak into another repo's `okl check`.
+
+Grep for `<<FILL` after scaffolding to find every slot you still need to complete:
+`grep -rn '<<FILL' .`
+
+## Stack profiles — real canon, not FILL slots
+
+The `<<FILL>>` slots above are the empty path. If your repo's stack matches one the kit already knows,
+skip the FILL work and stamp a **profile** — verbatim canon lifted from a real repo, dropped straight
+into `.claude/rules/` as path-scoped rule files:
+
+| `--profile` | Source repo | Rule files | Path scope |
+|---|---|---|---|
+| `dotnet` | the .NET platform | architecture, security, performance-and-data, messaging | `**/*.cs`, endpoints, features |
+| `geospatial` | the geospatial pipeline | geospatial-ml | `**/*.py`, `**/*.yaml` |
+| `python-rag` | the RAG service | rag-pipeline, fastapi-backend, project-structure | `**/*.py`, `**/main.py` |
+| `react` | the .NET platform storefront | frontend | `frontend/**`, `**/frontend/**` |
+
+**Profiles compose** — `react` is backend-agnostic, so stack it onto any backend:
+
+```
+okl scaffold --profile dotnet --profile react        # .NET + React storefront
+okl scaffold --profile python-rag --profile react    # FastAPI backend + React SPA
+okl scaffold --profile geospatial                     # rslearn/OlmoEarth pipeline
+```
+
+Each profile also writes a `_PROFILE_<name>.md` into `.claude/rules/` documenting what it installed.
+Profile rules are the *static* half; the *cross-repo* half (defects, gates, retractions that move
+between repos) lives in okl and surfaces via `okl check`.

okl/scaffold/ci/method-gates.yml

@@ -0,0 +1,32 @@
+# Copy into .github/workflows/method-gates.yml
+# Surface 5 in CI: the mechanical drift-gates + the eval tier. Fail-closed — a red gate blocks merge.
+name: method-gates
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+jobs:
+  gates:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Run drift-gates (retractions / tombstones / doc-orphans / canon-size)
+        run: bash gates/run-gates.sh
+
+  evals:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+      - name: Run eval tier (leads with its own failure count; blocks if RESULTS NOT USABLE)
+        env:
+          GENERATOR_MODEL: ${{ vars.GENERATOR_MODEL }}
+          JUDGE_MODEL: ${{ vars.JUDGE_MODEL }}   # must differ from GENERATOR_MODEL
+        run: python evals/run_evals.py --fail-rate 0.20
+
+  # Optional: emit VERIFIED_ON receipts to the org knowledge layer when gates pass.
+  # See okl README + ci/okl-verify.yml.