org-knowledge-layer 0.4.0__tar.gz → 0.4.1__tar.gz

{org_knowledge_layer-0.4.0 → org_knowledge_layer-0.4.1}/.github/workflows/ci.yml

@@ -78,6 +78,18 @@ jobs:
       # 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"

{org_knowledge_layer-0.4.0/ci → org_knowledge_layer-0.4.1/.github/workflows}/okl-verify.yml

@@ -16,16 +16,45 @@ on:
   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:
-      - uses: actions/checkout@v4
+      # 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@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09  # v5
         with:
-          fetch-depth: 0   # drift needs history: it compares file mtimes/commits vs verified_at
-      - uses: actions/setup-python@v5
+          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@ece7cb06caefa5fff74198d8649806c4678c61a1  # v6
         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.
@@ -36,13 +65,10 @@ jobs:
             pip install org-knowledge-layer
           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 }}
+      - name: Report which store the gate will run against
         run: |
           if [ -n "${OKL_SERVICE_URL:-}" ]; then
-            okl connect "$OKL_SERVICE_URL" --token "$OKL_TOKEN"
+            echo "verifying against the shared layer at $OKL_SERVICE_URL"
           else
             echo "no OKL_SERVICE_URL secret — verifying against the repo-local store"
           fi

{org_knowledge_layer-0.4.0 → org_knowledge_layer-0.4.1}/CHANGELOG.md

@@ -1,5 +1,32 @@
 # Changelog
 
+## 0.4.1
+
+### Security — affects the CI workflow already in your repo
+
+- **The shipped CI verifier no longer writes your bearer token to disk.** It ran
+  `okl connect --token`, which persisted `OKL_TOKEN` into `.okl/config.json` on the runner
+  for no reason: the client reads `OKL_SERVICE_URL` and `OKL_TOKEN` from the environment
+  directly, so setting them at job level does the same work with the credential never
+  touching the filesystem. Re-run `okl init` (or `okl scaffold`) to pick up the new file.
+- **Both shipped workflows are hardened.** `okl-verify.yml` and `method-gates.yml` now
+  declare least-privilege `permissions`, a concurrency group, `pipefail`, and
+  `persist-credentials: false`, and pin their actions to commit SHAs rather than mutable
+  tags. They satisfied none of that before.
+- `.github/dependabot.yml` ships with the kit, because pinning to a SHA without an update
+  path is how a repo ends up on a two-year-old action and calls it hardening.
+
+### Added
+
+- **Opt-in architecture review in CI.** `ci/review-agent.sh` runs the reviewer over a PR
+  diff and fails on must-fix findings. **Off unless you set the `REVIEW_CMD` repository
+  variable** to a CLI that reads a prompt on stdin — `claude -p` (authenticates with an
+  existing Claude Code login, no separate API key), `ollama run <model>` (local, free), or
+  any other. Unset, it prints one line and passes. It is the only gate in the kit that
+  calls a model, which is why it is the only one that is opt-in. Documented in the README
+  and the kit manifest.
+
+
 ## 0.4.0
 
 ### Behaviour changes worth reading before upgrading

{org_knowledge_layer-0.4.0 → org_knowledge_layer-0.4.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: org-knowledge-layer
-Version: 0.4.0
+Version: 0.4.1
 Summary: Org Knowledge Layer — an installable sixth surface that carries encoded engineering lessons across repos.
 Author: Joshua Dell
 License: MIT
@@ -358,6 +358,32 @@ To remove okl from a repo entirely, delete `.okl/`, the two hook scripts and the
 in `.claude/settings.json`, and `.github/workflows/okl-verify.yml`. Nothing else was
 written, and nothing outside that repo was touched.
 
+### Architecture review in CI (off by default)
+
+The kit ships a reviewer that reads a PR diff against your encoded rules and fails the
+build on a must-fix finding. It is **off unless you ask for it**, and it is not tied to any
+vendor. Set the `REVIEW_CMD` repository variable to any CLI that reads a prompt on stdin:
+
+```bash
+gh variable set REVIEW_CMD --body "claude -p --model sonnet"   # your existing Claude Code login
+gh variable set REVIEW_CMD --body "ollama run qwen2.5-coder"   # local model, no API cost
+gh variable set REVIEW_CMD --body "llm -m gpt-4o"              # any other CLI
+```
+
+Two things worth knowing:
+
+- **`claude -p` needs no separate API key.** It authenticates with the Claude Code login you
+  already have, so if you use Claude Code there is nothing else to configure and no second
+  bill. Verified headless with `ANTHROPIC_API_KEY` unset.
+- **Locally you do not need this at all.** The reviewer is a subagent
+  (`.claude/agents/architecture-reviewer.md`); ask your agent to run it on your changes and
+  it costs nothing beyond the session you are already in. The CI job exists for the case
+  where no human and no agent is in the loop — a PR nobody reviewed.
+
+Unset, the step prints one line saying it is off and exits 0. Every other gate in the kit is
+deterministic and free; this is the only one that calls a model, which is why it is the only
+one that is opt-in.
+
 ## Wire a repo
 
 ```bash

{org_knowledge_layer-0.4.0 → org_knowledge_layer-0.4.1}/README.md

@@ -324,6 +324,32 @@ To remove okl from a repo entirely, delete `.okl/`, the two hook scripts and the
 in `.claude/settings.json`, and `.github/workflows/okl-verify.yml`. Nothing else was
 written, and nothing outside that repo was touched.
 
+### Architecture review in CI (off by default)
+
+The kit ships a reviewer that reads a PR diff against your encoded rules and fails the
+build on a must-fix finding. It is **off unless you ask for it**, and it is not tied to any
+vendor. Set the `REVIEW_CMD` repository variable to any CLI that reads a prompt on stdin:
+
+```bash
+gh variable set REVIEW_CMD --body "claude -p --model sonnet"   # your existing Claude Code login
+gh variable set REVIEW_CMD --body "ollama run qwen2.5-coder"   # local model, no API cost
+gh variable set REVIEW_CMD --body "llm -m gpt-4o"              # any other CLI
+```
+
+Two things worth knowing:
+
+- **`claude -p` needs no separate API key.** It authenticates with the Claude Code login you
+  already have, so if you use Claude Code there is nothing else to configure and no second
+  bill. Verified headless with `ANTHROPIC_API_KEY` unset.
+- **Locally you do not need this at all.** The reviewer is a subagent
+  (`.claude/agents/architecture-reviewer.md`); ask your agent to run it on your changes and
+  it costs nothing beyond the session you are already in. The CI job exists for the case
+  where no human and no agent is in the loop — a PR nobody reviewed.
+
+Unset, the step prints one line saying it is off and exits 0. Every other gate in the kit is
+deterministic and free; this is the only one that calls a model, which is why it is the only
+one that is opt-in.
+
 ## Wire a repo
 
 ```bash

{org_knowledge_layer-0.4.0/src/okl/scaffold → org_knowledge_layer-0.4.1}/ci/okl-verify.yml

@@ -16,16 +16,45 @@ on:
   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:
-      - uses: actions/checkout@v4
+      # 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@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09  # v5
         with:
-          fetch-depth: 0   # drift needs history: it compares file mtimes/commits vs verified_at
-      - uses: actions/setup-python@v5
+          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@ece7cb06caefa5fff74198d8649806c4678c61a1  # v6
         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.
@@ -36,13 +65,10 @@ jobs:
             pip install org-knowledge-layer
           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 }}
+      - name: Report which store the gate will run against
         run: |
           if [ -n "${OKL_SERVICE_URL:-}" ]; then
-            okl connect "$OKL_SERVICE_URL" --token "$OKL_TOKEN"
+            echo "verifying against the shared layer at $OKL_SERVICE_URL"
           else
             echo "no OKL_SERVICE_URL secret — verifying against the repo-local store"
           fi

org_knowledge_layer-0.4.1/ci/review-agent.sh

@@ -0,0 +1,133 @@
+#!/usr/bin/env bash
+# review-agent.sh — run the architecture reviewer over a PR diff, headless.
+#
+# Closes the gap the store names as "an enforcement surface that only runs on-demand runs
+# never": .claude/agents/architecture-reviewer.md is listed as a review surface but nothing
+# triggers it, so in practice it runs when someone remembers, which is never.
+#
+# OFF BY DEFAULT, AND VENDOR-NEUTRAL. Set REVIEW_CMD to any CLI that reads a prompt on
+# stdin and writes the model's reply to stdout:
+#
+#   REVIEW_CMD="claude -p --model sonnet"
+#   REVIEW_CMD="llm -m gpt-4o"
+#   REVIEW_CMD="ollama run qwen2.5-coder"        # local, no API cost at all
+#
+# Unset, the step soft-passes and says how to switch it on. okl is harness-agnostic —
+# hard-coding one vendor's CLI here would contradict that, and would hand every consumer
+# an API bill they never asked for. This mirrors GENERATOR_CMD/JUDGE_CMD in evals/.
+#
+# Self-owned on purpose: no third-party review SaaS holds a token for your source, and the
+# reviewer reads YOUR encoded rules (it calls `okl check` itself) rather than generic advice.
+set -uo pipefail
+cd "$(dirname "$0")/.."
+
+# Located, not assumed: `okl scaffold --claude-dir` lets a repo name that directory
+# something other than .claude, and a hard-coded path silently skips the review in exactly
+# those repos — a gate that quietly does nothing is the failure this whole file exists to
+# fix. AGENT_FILE overrides for anything unusual.
+AGENT="${AGENT_FILE:-}"
+if [ -z "$AGENT" ]; then
+  AGENT="$(find . -maxdepth 3 -path ./.git -prune -o \
+           -name architecture-reviewer.md -print 2>/dev/null | head -1)"
+fi
+BASE="${REVIEW_BASE_REF:-origin/main}"
+
+if [ -z "${REVIEW_CMD:-}" ]; then
+  echo "review-agent: REVIEW_CMD not set — skipping (soft pass)."
+  echo "  Set it to any CLI that takes a prompt on stdin to turn this into a blocking gate,"
+  echo "  e.g. REVIEW_CMD=\"claude -p --model sonnet\" or REVIEW_CMD=\"ollama run qwen2.5-coder\"."
+  exit 0
+fi
+if [ ! -f "$AGENT" ]; then
+  echo "review-agent: no $AGENT — skipping (the reviewer ships with \`okl scaffold\`)."
+  exit 0
+fi
+# shellcheck disable=SC2086 — REVIEW_CMD is a command line, so word splitting is intended
+if ! command -v ${REVIEW_CMD%% *} >/dev/null 2>&1; then
+  echo "review-agent: '${REVIEW_CMD%% *}' from REVIEW_CMD is not on PATH — skipping (soft pass)." >&2
+  exit 0
+fi
+
+diff_text="$(git diff "$BASE"...HEAD 2>/dev/null)"
+if [ -z "$diff_text" ]; then
+  echo "review-agent: no diff against $BASE — nothing to review."
+  exit 0
+fi
+
+# Truncate: a very large diff would blow the context budget and produce a worse review than
+# a focused one. Reviewing the first N lines and saying so beats silently reviewing a
+# truncated diff as though it were whole.
+max_lines=4000
+total_lines=$(printf '%s' "$diff_text" | wc -l | tr -d ' ')
+if [ "$total_lines" -gt "$max_lines" ]; then
+  diff_text="$(printf '%s' "$diff_text" | head -n "$max_lines")"
+  echo "review-agent: diff is $total_lines lines; reviewing the first $max_lines."
+fi
+
+# The checklist lives in the agent file — one source of truth for the rules. Only the OUTPUT
+# CONTRACT is supplied here, because the agent is written for interactive use and returns
+# prose, which CI cannot act on.
+prompt="$(cat <<EOF
+You are the architecture reviewer defined below. Apply its checklist to the diff.
+
+$(cat "$AGENT")
+
+--- DIFF UNDER REVIEW ---
+$diff_text
+--- END DIFF ---
+
+Reply with STRICT JSON and nothing else:
+{"findings":[{"severity":"must-fix|consider","file":"path","line":0,"rule":"which checklist item","finding":"one sentence"}]}
+
+Rules for your reply:
+- "must-fix" is reserved for a violation of an encoded rule: a restated retraction, a
+  resurrected tombstoned identifier, a speculative abstraction, an assert-from-memory claim.
+  Style preferences and suggestions are "consider".
+- Only report what this diff introduces. Pre-existing issues are out of scope.
+- An empty findings list is a valid and common answer. Do not invent findings to seem useful.
+EOF
+)"
+
+echo "review-agent: reviewing $(printf '%s' "$diff_text" | wc -l | tr -d ' ') lines of diff against $BASE"
+# CLEAN ROOM. Run the reviewer from a temp directory, never the repo. If REVIEW_CMD is a
+# coding agent, this repo's own hooks would otherwise fire on it: the UserPromptSubmit hook
+# injects a briefing into the review, and the Stop hook answers instead of the reviewer.
+# Reproduced while verifying this script — a smoke call in the repo cwd came back answering
+# the Stop hook rather than the question, which is the same failure evals/ documents.
+clean="$(mktemp -d)"
+raw="$(cd "$clean" && printf '%s' "$prompt" | $REVIEW_CMD 2>/dev/null)"
+rmdir "$clean" 2>/dev/null || true
+
+# Strip any markdown fence the model adds around the JSON.
+json="$(printf '%s' "$raw" | sed -e 's/^```json//' -e 's/^```//' -e '/^```$/d')"
+
+if ! printf '%s' "$json" | python3 -c "import json,sys; json.load(sys.stdin)" 2>/dev/null; then
+  # Fail OPEN on an unparseable reply, loudly. A reviewer that cannot be understood has not
+  # found anything; blocking every merge on a malformed model response would train people to
+  # bypass the gate, which is worse than the gate not firing.
+  echo "review-agent: could not parse the reviewer's reply as JSON — not blocking." >&2
+  printf '%s\n' "$raw" | head -20 >&2
+  exit 0
+fi
+
+printf '%s' "$json" | python3 -c '
+import json, sys
+
+# %-formatting rather than f-strings: this is embedded in a shell single-quoted string, so
+# the keys need double quotes, and a backslash inside an f-string EXPRESSION is a SyntaxError
+# before Python 3.12 — which this must survive, since it runs on whatever interpreter the
+# consumer has. The first version hit exactly that and exited 1 on every run. A gate that
+# always blocks looks identical to a gate that works until someone notices nothing has ever
+# passed it.
+findings = json.load(sys.stdin).get("findings", [])
+must = [f for f in findings if f.get("severity") == "must-fix"]
+for f in findings:
+    mark = "MUST-FIX" if f.get("severity") == "must-fix" else "consider"
+    print("  [%s] %s:%s  %s" % (mark, f.get("file"), f.get("line"), f.get("rule")))
+    print("            %s" % f.get("finding"))
+if not findings:
+    print("  no findings")
+print()
+print("review-agent: %d must-fix, %d to consider" % (len(must), len(findings) - len(must)))
+sys.exit(1 if must else 0)
+'

{org_knowledge_layer-0.4.0 → org_knowledge_layer-0.4.1}/pyproject.toml

@@ -6,7 +6,7 @@ build-backend = "hatchling.build"
 # Distribution name only. The CLI command, the import package, and the repo are all `okl`;
 # PyPI rejects `okl` as too similar to the existing `oki` (l/i are treated as confusable).
 name = "org-knowledge-layer"
-version = "0.4.0"
+version = "0.4.1"
 description = "Org Knowledge Layer — an installable sixth surface that carries encoded engineering lessons across repos."
 readme = "README.md"
 requires-python = ">=3.10"

{org_knowledge_layer-0.4.0 → org_knowledge_layer-0.4.1}/src/okl/scaffold/MANIFEST.md

@@ -57,3 +57,11 @@ okl scaffold --profile geospatial                     # rslearn/OlmoEarth pipeli
 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`.
+
+## Architecture review (opt-in)
+
+`ci/review-agent.sh` runs `.claude/agents/architecture-reviewer.md` over a PR diff and
+fails on must-fix findings. **Off unless the `REVIEW_CMD` repository variable is set** to
+a CLI that reads a prompt on stdin — `claude -p` (uses your existing Claude Code login,
+no separate API key), `ollama run <model>` (local, free), or any other. Unset, it prints
+one line and passes. It is the only gate in this kit that calls a model.

org_knowledge_layer-0.4.1/src/okl/scaffold/ci/dependabot.yml

@@ -0,0 +1,17 @@
+# Copy into .github/dependabot.yml
+#
+# This exists because the shipped workflows pin their actions to commit SHAs. Pinning
+# 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 with no 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"

org_knowledge_layer-0.4.1/src/okl/scaffold/ci/method-gates.yml

@@ -0,0 +1,74 @@
+# 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]
+
+# Least privilege: these jobs read code and report a status. Neither writes.
+permissions:
+  contents: read
+
+concurrency:
+  group: method-gates-${{ 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 — which defeats the point of a fail-closed gate.
+    shell: bash -euo pipefail {0}
+
+jobs:
+  gates:
+    runs-on: ubuntu-latest
+    steps:
+      # Pinned to a commit SHA, not a tag: a tag is mutable, so `@v5` is an unpinned
+      # dependency with access to your runner. Add a .github/dependabot.yml with the
+      # `github-actions` ecosystem so these pins receive security updates — a pin with no
+      # update path goes stale, which is its own risk.
+      - uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09  # v5
+        with:
+          persist-credentials: false
+      - 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@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09  # v5
+        with:
+          persist-credentials: false
+      - uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1  # v6
+        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
+
+  review:
+    # The architecture reviewer, run headless on the PR diff. OFF unless you set the
+    # REVIEW_CMD repository variable to a CLI that takes a prompt on stdin — any vendor,
+    # or a local model. Installing the kit costs you nothing and calls nobody's API.
+    if: github.event_name == 'pull_request'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09  # v5
+        with:
+          fetch-depth: 0   # the reviewer diffs against the base branch
+          persist-credentials: false
+      - name: Architecture review (off unless REVIEW_CMD is set)
+        env:
+          REVIEW_CMD: ${{ vars.REVIEW_CMD }}
+          # Whatever credential your REVIEW_CMD needs, named by you. Unset is fine.
+          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
+          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
+          REVIEW_BASE_REF: origin/${{ github.base_ref }}
+        run: bash ci/review-agent.sh
+
+  # Optional: emit VERIFIED_ON receipts to the org knowledge layer when gates pass.
+  # See okl README + ci/okl-verify.yml.

{org_knowledge_layer-0.4.0/.github/workflows → org_knowledge_layer-0.4.1/src/okl/scaffold/ci}/okl-verify.yml

@@ -16,16 +16,45 @@ on:
   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:
-      - uses: actions/checkout@v4
+      # 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@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09  # v5
         with:
-          fetch-depth: 0   # drift needs history: it compares file mtimes/commits vs verified_at
-      - uses: actions/setup-python@v5
+          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@ece7cb06caefa5fff74198d8649806c4678c61a1  # v6
         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.
@@ -36,13 +65,10 @@ jobs:
             pip install org-knowledge-layer
           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 }}
+      - name: Report which store the gate will run against
         run: |
           if [ -n "${OKL_SERVICE_URL:-}" ]; then
-            okl connect "$OKL_SERVICE_URL" --token "$OKL_TOKEN"
+            echo "verifying against the shared layer at $OKL_SERVICE_URL"
           else
             echo "no OKL_SERVICE_URL secret — verifying against the repo-local store"
           fi