observed-knowledge-ledger 0.6.0__tar.gz

observed_knowledge_ledger-0.6.0/.claude/agent-memory/architecture-reviewer/MEMORY.md

@@ -0,0 +1 @@
+- [Review findings log](review_findings_log.md) — recurring finding classes with counts; promote to a gate at 3

observed_knowledge_ledger-0.6.0/.claude/agent-memory/architecture-reviewer/review_findings_log.md

@@ -0,0 +1,15 @@
+---
+name: review-findings-log
+description: Recurring architecture-review finding classes in okl, with counts, to decide when to promote one to a mechanical gate
+metadata:
+  type: project
+---
+
+Tally of finding classes seen in okl reviews. At 3 occurrences, propose a gate via encoding-loop.
+
+- **_Backend Protocol method added without a behavioural clause in its docstring** — 1 (PR #35, `edges()`, 2026-09-24). Related record: "A port is defined by behaviour, not by its signatures".
+- **Old and new computation of one metric both served (two sources of truth)** — 1 (PR #35: `recurrence_after_arming` SQL kept beside `core.recurrence_report`).
+- **Postgres-backend change reaches CI untested** — 1 (PR #35). CI has no Postgres service; `test_postgres_backend_conformance` is skipped unless OKL_TEST_POSTGRES_URL is set.
+
+**Why:** the agent brief asks to promote a finding class to a gate at its third sighting.
+**How to apply:** bump the count when a class recurs; at 3, recommend a gate (e.g. a test that every _Backend method is named in the Protocol docstring).

observed_knowledge_ledger-0.6.0/.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.

observed_knowledge_ledger-0.6.0/.claude/hooks/stop-okl-encode.sh

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

observed_knowledge_ledger-0.6.0/.claude/hooks/userpromptsubmit-okl-check.sh

@@ -0,0 +1,70 @@
+#!/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 observed-knowledge-ledger. NOT 'pip install okl' — PyPI refuses that" >&2
+  echo "name as confusable, so it fails and looks like the tool does not exist." >&2
+  echo "Or set OKL_BIN, or re-run 'okl init' from a shell where okl works (that pins okl_bin" >&2
+  echo "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

observed_knowledge_ledger-0.6.0/.claude/settings.json

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

observed_knowledge_ledger-0.6.0/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,21 @@
+---
+name: Bug report
+about: Something behaves differently than documented
+labels: bug
+---
+
+**What you ran** (the exact command, and `okl --help` version if relevant)
+
+**What you expected**
+
+**What actually happened** (paste the real output, not a summary)
+
+**Environment**
+- OS:
+- Python:
+- Installed via: `pip install observed-knowledge-ledger` / `pip install -e .`
+- Mode: local store / shared service
+
+**Especially useful:** if the tool reported success it had not earned (a check that
+passed without running, a stamp without evidence, a hook that fired but changed
+nothing), say so explicitly. That class of defect is this project's subject.

observed_knowledge_ledger-0.6.0/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,15 @@
+---
+name: Proposal
+about: Suggest a change to how the loop works
+labels: proposal
+---
+
+**The symptom you hit** (what went wrong in real use, not the feature you want)
+
+**Why the current design does not cover it**
+
+**What you would change**
+
+**How you would know it worked** — the check, measurement, or test that would show it.
+Proposals that name their own evidence get adopted faster; see `evals/REPORT.md` for
+the standard this repo holds itself to.

observed_knowledge_ledger-0.6.0/.github/dependabot.yml

@@ -0,0 +1,32 @@
+# Dependabot.
+#
+# This exists because of the SHA pinning, not despite it. Pinning actions to a commit
+# closes the "a mutable tag moved under me" hole and opens a quieter one: the pin never
+# updates, so a security fix in an action never arrives. Pinning without an update path
+# is how a repo ends up on a two-year-old checkout action and calls it hardening.
+# Dependabot rewrites the SHA and the trailing `# v5` comment together.
+version: 2
+
+updates:
+  - package-ecosystem: github-actions
+    directory: "/"
+    schedule:
+      interval: weekly
+    labels: ["dependencies", "ci"]
+    commit-message:
+      prefix: "ci"
+
+  - package-ecosystem: pip
+    directory: "/"
+    schedule:
+      interval: weekly
+    labels: ["dependencies"]
+    commit-message:
+      prefix: "deps"
+    # The gating tools are pinned exactly on purpose (a range lets a new release
+    # retro-fail a branch that changed nothing). Dependabot is the intended way to move
+    # those pins: a PR that runs the full suite against the new version before it lands,
+    # rather than a range that upgrades silently mid-branch.
+    groups:
+      dev-tooling:
+        patterns: ["pytest", "ruff", "mypy"]

observed_knowledge_ledger-0.6.0/.github/pull_request_template.md

@@ -0,0 +1,15 @@
+## What changed
+
+## Why
+
+## What you ran to check it
+
+<!-- Paste real output. `pytest -q`, `ruff check .`, and `okl drift` at minimum. -->
+
+## Checklist
+
+- [ ] `pytest -q` green
+- [ ] `ruff check .` clean
+- [ ] `okl drift` green, or affected records re-verified with `okl verify --run`
+- [ ] Mirror files still byte-identical (`ci/`, `.github/workflows/`, `hooks/` and their `src/okl/scaffold/` twins)
+- [ ] Any number quoted has a committed receipt in `evals/results/`

observed_knowledge_ledger-0.6.0/.github/workflows/ci.yml

@@ -0,0 +1,100 @@
+# Repo CI — lints, type-checks and tests okl itself. (okl-verify.yml is different: it
+# demonstrates the product's own drift/method gates, the workflow consumers copy.)
+#
+# Hardened per the org rule this repo's own store carries ("CI workflow baseline:
+# pipefail, no persisted credentials, least-privilege permissions, concurrency groups —
+# pin actions"). It satisfied none of the five until this commit, which is the rule's own
+# symptom: an enforcement surface nothing triggers runs never.
+name: ci
+
+on:
+  push:
+    branches: [ "main" ]
+  pull_request:
+    branches: [ "main" ]
+
+# Least privilege: this job reads code and reports status. It never pushes.
+permissions:
+  contents: read
+
+# One run per ref. A superseded push should stop burning minutes on a result nobody
+# will read.
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+defaults:
+  run:
+    # Without pipefail a run block continues past a failed segment of a pipeline, so a
+    # green step can hide a red command.
+    shell: bash -euo pipefail {0}
+
+jobs:
+  lint-and-test:
+    runs-on: ubuntu-latest
+    steps:
+      # Actions pinned to a commit SHA, not a tag: a tag is mutable, so `@v5` is an
+      # unpinned dependency with write access to the runner.
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
+        with:
+          # The diagram gate reads committed history (git show HEAD:...), not the
+          # checkout tree, so it needs more than the default shallow fetch.
+          fetch-depth: 0
+          # This job never pushes; leaving the token in .git/config lets any later step
+          # (or a compromised dependency) use it.
+          persist-credentials: false
+
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97  # v7.0.0
+        with:
+          python-version: "3.12"
+
+      - name: Install (dev extras)
+        run: pip install -e ".[dev]"
+
+      - name: Lint — ruff (config in pyproject.toml)
+        run: ruff check .
+
+      - name: Types — mypy
+        run: mypy src/okl
+
+      - name: Tests (with the coverage ratchet)
+        run: pytest -q --cov=okl
+
+      - name: Diagram figures trace to committed receipts
+        run: ./ci/check-diagram-figures.sh
+
+      # The content audits okl ships to consumers, run against okl itself. They were
+      # shipped for weeks without this repo running any of them — the "enforcement
+      # surface nothing triggers" failure, one level up: a gate whose author has never
+      # run it on their own tree.
+      - name: Method gates (links, doc orphans, diagram pairs, tombstones, canon size)
+        run: bash gates/run-gates.sh
+
+      # Secret scan over the FULL history, not the working tree. okl writes a bearer
+      # token into .okl/config.json, and the .gitignore it now drops there is the only
+      # thing between that and a commit — this is the check for when that fails.
+      #
+      # The upstream gitleaks-action is deliberately not used: it requires a paid licence
+      # key for organization-owned repositories, so it would break for anyone who forks
+      # this into an org. The binary has no such condition, and pinning the release keeps
+      # a new detection rule from retro-failing a branch that changed nothing.
+      # The reviewer okl ships, run on okl. It was listed as a review surface with nothing
+      # triggering it — the "enforcement surface that only runs on-demand runs never"
+      # failure this repo's own store names. Off unless REVIEW_CMD is set, so it costs
+      # nothing until someone decides it should.
+      - name: Architecture review (off unless REVIEW_CMD is set)
+        if: github.event_name == 'pull_request'
+        env:
+          REVIEW_CMD: ${{ vars.REVIEW_CMD }}
+          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
+          REVIEW_BASE_REF: origin/${{ github.base_ref }}
+        run: bash ci/review-agent.sh
+
+      - name: Secret scan — gitleaks
+        env:
+          GITLEAKS_VERSION: "8.30.1"
+        run: |
+          curl -sSfL -o /tmp/gitleaks.tar.gz \
+            "https://github.com/gitleaks/gitleaks/releases/download/v${GITLEAKS_VERSION}/gitleaks_${GITLEAKS_VERSION}_linux_x64.tar.gz"
+          tar -xzf /tmp/gitleaks.tar.gz -C /tmp gitleaks
+          /tmp/gitleaks git . --no-banner --redact --exit-code 1

observed_knowledge_ledger-0.6.0/.github/workflows/okl-verify.yml

@@ -0,0 +1,120 @@
+# 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 reads the
+# committed snapshot okl-drift.json (`okl export --drift`; `okl verify` keeps it current),
+# which also covers fork PRs, since they get no secrets. 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]
+
+# Least privilege: this workflow reads code and reports a status. It never writes.
+permissions:
+  contents: read
+
+concurrency:
+  group: okl-verify-${{ github.ref }}
+  cancel-in-progress: true
+
+defaults:
+  run:
+    # Without pipefail a run block continues past a failed segment of a pipeline, so a
+    # green step can hide a red command.
+    shell: bash -euo pipefail {0}
+
+jobs:
+  okl-verify:
+    runs-on: ubuntu-latest
+    env:
+      # Set at job level so every okl command below resolves the shared layer from the
+      # environment. This replaces an `okl connect --token` step, which wrote the bearer
+      # token into .okl/config.json on the runner — needless, since the client reads both
+      # variables directly, and one more place for a credential to end up.
+      # Unset secrets leave these empty, and okl falls back to the repo-local store.
+      OKL_SERVICE_URL: ${{ secrets.OKL_SERVICE_URL }}
+      OKL_TOKEN: ${{ secrets.OKL_TOKEN }}
+    steps:
+      # Actions are pinned to a commit SHA: a tag is mutable, so `@v5` is an unpinned
+      # dependency with access to your runner. If you copy this file into your own repo,
+      # add a .github/dependabot.yml with the `github-actions` ecosystem so these pins get
+      # security updates — a pin with no update path goes stale and that is its own risk.
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
+        with:
+          fetch-depth: 0   # drift needs history: it compares governed-file commits vs verified_at
+          persist-credentials: false   # this job never pushes
+
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97  # v7.0.0
+        with:
+          python-version: "3.13"
+
+      - name: Install okl
+        # Detect by the package source, not the distribution name: the name changed once
+        # (PyPI rejects "okl" as confusable) and a name-based check silently broke with it.
+        run: |
+          if [ -f src/okl/cli.py ]; then
+            pip install -e .
+          else
+            pip install observed-knowledge-ledger
+          fi
+
+      - name: Report which store the gate will run against
+        run: |
+          if [ -n "${OKL_SERVICE_URL:-}" ]; then
+            echo "verifying against the shared layer at $OKL_SERVICE_URL"
+          elif git ls-files --error-unmatch okl-drift.json >/dev/null 2>&1; then
+            echo "no OKL_SERVICE_URL secret — verifying against the committed okl-drift.json"
+          else
+            echo "no OKL_SERVICE_URL secret and no committed okl-drift.json — nothing to verify against"
+          fi
+
+      - name: Drift gate — rules whose governed code changed after last verification
+        # The exit code is the verdict: 0 checked and clean, 1 drift found, 2 did not run.
+        # "Did not run" is the case this step used to report as a pass: with no store in CI
+        # (okl init gitignores it) the gate checked nothing and printed OK. It now says so,
+        # as a warning annotation on the PR rather than a failure, because an unseeded
+        # store is a setup gap, not a defect in the change under review -- and failing on it
+        # would block every pull request from the moment okl is installed. To make this
+        # step a real check, give CI a store: commit `okl export --drift`, or set the
+        # OKL_SERVICE_URL secret. A committed snapshot IS a store for this purpose, so once
+        # one exists, exit 2 fails like any other configured store.
+        run: |
+          snapshot=""
+          if [ -z "${OKL_SERVICE_URL:-}${OKL_DATABASE_URL:-}" ] \
+             && git ls-files --error-unmatch okl-drift.json >/dev/null 2>&1; then
+            snapshot="okl-drift.json"
+          fi
+          set +e
+          if [ -n "$snapshot" ]; then
+            okl drift --gate --snapshot "$snapshot"
+          else
+            okl drift --gate
+          fi
+          rc=$?
+          set -e
+          # Exit 2 means "did not run", which has two causes that deserve opposite outcomes.
+          # If this job was never given a store, it is the setup gap above: warn. If a store
+          # WAS configured and okl still did not run -- unreachable, refused, or holding no
+          # rule for this repo -- something broke, and passing would hide an outage behind
+          # a green check. The job knows which it is; okl's exit code alone cannot say.
+          if [ "$rc" -eq 2 ] && [ -z "${OKL_SERVICE_URL:-}${OKL_DATABASE_URL:-}${snapshot}" ]; then
+            echo "::warning title=Drift not checked::No knowledge store is available to this job, so no rule was checked for drift. This step passing is NOT an all-clear. Commit \`okl export --drift\` to give CI one."
+          elif [ "$rc" -ne 0 ]; then
+            exit "$rc"
+          fi
+
+      - 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

observed_knowledge_ledger-0.6.0/.github/workflows/publish.yml

@@ -0,0 +1,99 @@
+# Release to PyPI on a version tag, using Trusted Publishing.
+#
+# There is no API token anywhere in this workflow, and none stored in the repository.
+# PyPI accepts the upload because GitHub vouches for it: the publish job mints a
+# short-lived OIDC token that names this repository, this workflow file and this
+# environment, and PyPI checks that against the trusted publisher it was told to expect.
+# A leaked repository secret cannot publish okl because there is no such secret.
+#
+# ONE-TIME SETUP ON PYPI (this workflow does nothing until it is done). The project was
+# renamed from org-knowledge-layer in 0.6.0: the NEW name needs its own pending publisher
+# below, and the old project keeps the one it already has (it publishes the redirect):
+#   pypi.org → the observed-knowledge-ledger project → Publishing → Add a pending publisher
+#     Owner:            emeraldleaf
+#     Repository:       okl
+#     Workflow name:    publish.yml
+#     Environment name: pypi
+# Then create the `pypi` environment under repo Settings → Environments. Adding a
+# required reviewer there makes every release a deliberate, approved act.
+name: publish
+
+on:
+  push:
+    tags: ["v*"]
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
+        with:
+          persist-credentials: false
+
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97  # v7.0.0
+        with:
+          python-version: "3.12"
+
+      # The tag is the release's claim about what version this is; pyproject.toml is the
+      # version that actually gets uploaded. When they disagree, PyPI takes pyproject's
+      # answer and the tag becomes a lie that is permanent — you cannot reuse a version
+      # number on PyPI, so the mistake is not fixable, only worked around.
+      - name: Tag must match the version in pyproject.toml
+        run: |
+          tag="${GITHUB_REF_NAME#v}"
+          pkg="$(python -c "import tomllib,pathlib; print(tomllib.loads(pathlib.Path('pyproject.toml').read_text())['project']['version'])")"
+          echo "tag=$tag  pyproject=$pkg"
+          if [ "$tag" != "$pkg" ]; then
+            echo "::error::tag v$tag does not match pyproject version $pkg"
+            exit 1
+          fi
+
+      - name: Build
+        run: |
+          python -m pip install --upgrade build twine
+          python -m build
+          # The old distribution name's final release (packaging/org-knowledge-layer):
+          # built only on the tag that matches its version, so it is published exactly
+          # once. Its PyPI project already trusts this workflow.
+          shim="$(python -c "import tomllib,pathlib; print(tomllib.loads(pathlib.Path('packaging/org-knowledge-layer/pyproject.toml').read_text())['project']['version'])")"
+          if [ "${GITHUB_REF_NAME#v}" = "$shim" ]; then
+            python -m build packaging/org-knowledge-layer --outdir dist/
+          fi
+          # `twine check` catches a malformed long_description, which PyPI rejects only
+          # after the upload has otherwise succeeded.
+          python -m twine check dist/*
+
+      - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a  # v7.0.1
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    # A named environment is what the PyPI trusted publisher is bound to, and it is where
+    # a required-reviewer rule can gate the release.
+    environment:
+      name: pypi
+      url: https://pypi.org/project/observed-knowledge-ledger/
+    permissions:
+      id-token: write      # mint the OIDC token PyPI verifies
+      attestations: write  # sign the artifacts
+      contents: read
+    steps:
+      - uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c  # v8.0.1
+        with:
+          name: dist
+          path: dist/
+
+      # Provenance: a signed statement that these exact files were built by this workflow
+      # from this commit. It is what lets someone verify the wheel on PyPI came from the
+      # source they are reading, rather than trusting that it did.
+      - uses: actions/attest-build-provenance@4d101475d8b20a2381f78447822ac1eab6504dd8  # v4.2.2
+        with:
+          subject-path: "dist/*"
+
+      - uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33  # release/v1