org-knowledge-layer 0.1.0__tar.gz → 0.1.2__tar.gz

{org_knowledge_layer-0.1.0 → org_knowledge_layer-0.1.2}/.claude/settings.local.json

@@ -67,7 +67,30 @@
       "Bash(./oklbuild/bin/pip install *)",
       "Bash(./oklbuild/bin/pip show *)",
       "Bash(/tmp/oklbuild/bin/python -m build --no-isolation)",
-      "Bash(unzip -p dist/*.whl \"*/entry_points.txt\")"
+      "Bash(unzip -p dist/*.whl \"*/entry_points.txt\")",
+      "Bash(git -c core.hooksPath=/dev/null commit -qm 'Publish as org-knowledge-layer: PyPI blocks '\\\\''okl'\\\\'' as confusable with '\\\\''oki'\\\\'' *)",
+      "Bash(rm -rf okltest)",
+      "Bash(python3 -m venv okltest)",
+      "Bash(./okltest/bin/pip install *)",
+      "Bash(./okltest/bin/okl --help)",
+      "Bash(./okltest/bin/python -c ' *)",
+      "Bash(git -c core.hooksPath=/dev/null commit -qm 'v0.1.1: lead the README with the install/command distinction *)",
+      "Bash(curl -s https://pypi.org/pypi/org-knowledge-layer/json)",
+      "Bash(curl -s https://emeraldleaf.dev/writing/enforcement-or-good-intentions/)",
+      "Bash(curl -s https://emeraldleaf.dev/writing/memory-that-outlives-the-run/)",
+      "Bash(curl -s https://emeraldleaf.dev/practice/)",
+      "Bash(git -C \"/Users/joshuadell/Dev/emeraldleaf-dev\" status --porcelain)",
+      "Bash(git -C \"/Users/joshuadell/Dev/emeraldleaf-dev\" log --oneline -1)",
+      "Bash(command -v rsvg-convert qlmanage)",
+      "Bash(node scripts/validate_palette.js \"#2a78d6,#eb6834\" --mode light)",
+      "Bash(rsvg-convert -w 1200 -h 720 docs/ab-results-chart.svg -o docs/ab-results-chart.png)",
+      "Bash(rsvg-convert -w 1200 -h 1200 docs/ab-results-chart.svg -o docs/ab-results-chart.png)",
+      "Bash(rsvg-convert -w 550 -h 550 docs/ab-results-chart.svg -o /tmp/chart-feedsize.png)",
+      "Bash(git -c core.hooksPath=/dev/null commit -qm 'Say what the store holds: rules, architecture decisions, known defects *)",
+      "Bash(git -c core.hooksPath=/dev/null commit -qm 'Post 1: concede the crowded category, name the narrow differentiator *)",
+      "Bash(git -c core.hooksPath=/dev/null commit -qm 'Public-repo hygiene: SECURITY.md, CONTRIBUTING.md, templates, provenance wording *)",
+      "Bash(grep -n \"^  [a-z-]*:$\\\\|^name:\\\\|runs-on\" .github/workflows/ci.yml)",
+      "Bash(git -C /Users/joshuadell/Dev/okl push --dry-run origin main)"
     ],
     "additionalDirectories": [
       "/Users/joshuadell/Dev/okl/e2e/scratch-briefed/.okl",

org_knowledge_layer-0.1.2/.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 org-knowledge-layer` / `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.

org_knowledge_layer-0.1.2/.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.

org_knowledge_layer-0.1.2/.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/`

org_knowledge_layer-0.1.2/CONTRIBUTING.md

@@ -0,0 +1,70 @@
+# Contributing
+
+Thanks for looking. This is a v0 project with one maintainer, so the most useful
+contributions are small, verifiable, and self-contained.
+
+## Setup
+
+```bash
+git clone https://github.com/emeraldleaf/okl && cd okl
+pip install -e ".[dev]"
+pytest -q          # must be green before and after your change
+ruff check .
+```
+
+Try it end to end in a scratch directory before changing anything:
+
+```bash
+mkdir /tmp/try && cd /tmp/try && git init
+okl init --repo try --interests security
+okl seed
+okl check --task "add an endpoint that returns an order for the logged-in user"
+```
+
+## The repo has rules about itself
+
+Read [CLAUDE.md](CLAUDE.md) (identical to AGENTS.md) before a first PR. It is short, and
+it is the actual contract. The parts that will fail your build if you miss them:
+
+- **Mirror files are byte-identical.** `ci/okl-verify.yml`, `.github/workflows/okl-verify.yml`
+  and `src/okl/scaffold/ci/okl-verify.yml` must match, as must `hooks/*.sh` and their
+  `src/okl/scaffold/hooks/` twins. Edit one, copy to the others in the same change.
+  `tests/test_scaffold.py::test_mirror_files_identical` enforces it.
+- **`okl drift` goes red when you change a file a stored rule governs.** That is the
+  system working. Re-verify the affected records with an actual check:
+  `okl verify <id> --run "pytest -q -k <test>" --expect "passed"`. Do not clear drift by
+  re-recording with `--verified`; the whole point is that stamps come from observed runs.
+- **Tags come from a closed vocabulary** (`store.KNOWN_TAGS`). Growing it is a deliberate
+  edit to that set plus a note in the tags ADR, not an ad-hoc string.
+- **Evaluation claims need a committed receipt.** If you change the harness or quote a
+  number, the run that produced it belongs in `evals/results/`. Never cite a run the
+  harness marked RESULTS NOT USABLE.
+
+## What is most welcome
+
+- **Bug reports with a reproduction.** Especially anything where the tool reports success
+  it did not earn; that class of defect is the project's whole subject.
+- **The open work in the store.** `okl check --task "improve retrieval precision"` will
+  show you the recorded defects against the tool itself, including the briefing relevance
+  cutoff that is still unfinished.
+- **Portability fixes.** Hooks, path resolution, and CI have been exercised on macOS and
+  GitHub Actions and nowhere else.
+- **A live-Postgres test.** The ranked search path for Postgres is currently asserted at
+  the SQL-shape level against a fake connection; it has never run against a real server.
+
+## What is out of scope for now
+
+Embedding or vector retrieval, unless one of the triggers in
+[the flat-retrieval ADR](docs/decisions/2026-07-17-flat-retrieval-until-scale.md) has
+actually fired and you bring the measurement showing it. The decision is falsifiable on
+purpose; falsify it with data rather than preference.
+
+## Pull requests
+
+Keep them single-purpose. Say what you changed and what you ran to check it, and include
+the real output rather than a description of it. If your change surfaced something
+non-obvious, record it in the store the way the repo records its own findings; a PR that
+teaches the system something is worth more than one that only fixes code.
+
+By contributing you agree your work is licensed under the repository's
+[MIT License](LICENSE).

{org_knowledge_layer-0.1.0 → org_knowledge_layer-0.1.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: org-knowledge-layer
-Version: 0.1.0
+Version: 0.1.2
 Summary: Org Knowledge Layer — an installable sixth surface that carries encoded engineering lessons across repos.
 Author: Joshua Dell
 License: MIT
@@ -37,6 +37,14 @@ Description-Content-Type: text/markdown
 > be broken — plus a command that hands the relevant ones to a coding agent (or a
 > person) **before** they start a task, so the same mistake isn't made twice.
 
+```bash
+pipx install org-knowledge-layer   # the distribution name on PyPI
+okl --help                         # the command, the import package, and the repo are all `okl`
+```
+
+*(PyPI rejects `okl` itself as confusable with the existing `oki`, so only the install
+line differs — everything you type afterwards is `okl`.)*
+
 ## The problem it solves
 
 A team (or an AI agent) fixes a subtle bug, learns *why* it happened, and writes a
@@ -216,18 +224,18 @@ knowledge. The switch is one environment variable; none of your commands change.
 ## Install
 
 ```bash
-pipx install okl            # once it's published; for now:
-pip install -e .            # from this repo
+pipx install org-knowledge-layer   # provides the `okl` command
+pip install -e .                   # or from a clone of this repo
 ```
 
 The core (local + client + CLI) is **stdlib-only** — zero required dependencies.
 Extras are opt-in:
 
 ```bash
-pip install "okl[service]"    # FastAPI shared service
-pip install "okl[postgres]"   # Postgres backend (psycopg)
-pip install "okl[mcp]"        # MCP server for Claude Code / Cursor / Copilot
-pip install "okl[all]"
+pip install "org-knowledge-layer[service]"    # FastAPI shared service
+pip install "org-knowledge-layer[postgres]"   # Postgres backend (psycopg)
+pip install "org-knowledge-layer[mcp]"        # MCP server for Claude Code / Cursor / Copilot
+pip install "org-knowledge-layer[all]"
 ```
 
 ## Wire a repo
@@ -403,19 +411,23 @@ okl serve --port 8080
 ## Run the shared service
 
 ```bash
-pip install "okl[service]"
+pip install "org-knowledge-layer[service]"
 OKL_DATABASE_URL="sqlite:///okl.db" OKL_TOKEN="a-shared-secret" okl serve
 # repos then: okl connect https://your-host --token a-shared-secret
 ```
 
-`OKL_TOKEN` (optional) gates **writes**; reads stay open. Deploy the service
+`OKL_TOKEN` (optional) gates **writes**; **reads stay open** — `/nodes` returns the
+whole store to anyone who can reach the port. A mature store holds your defect history,
+security patterns and internal architecture, so treat it as sensitive: bind it to a
+private network or put authentication in front of every route before exposing it. See
+[SECURITY.md](SECURITY.md). Deploy the service
 wherever you like — it's storage-agnostic by design (a `Dockerfile` and a
 `fly.toml` are the obvious next commit; not included in v0).
 
 ## Agent integration (MCP)
 
 ```bash
-pip install "okl[mcp]"
+pip install "org-knowledge-layer[mcp]"
 okl mcp     # register in your coding agent's tool config
 ```
 
@@ -466,10 +478,16 @@ tests/            # end-to-end tests
 ## Test
 
 ```bash
-pip install "okl[dev]"
+pip install "org-knowledge-layer[dev]"
 pytest -q          # full suite (one drift test self-skips where git init is unavailable)
 ```
 
 ## License
 
 MIT.
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for setup, the repo's own rules (mirror files,
+drift, evidence-based verification), and where help is most useful. Security policy and
+the deployment threat model: [SECURITY.md](SECURITY.md).

{org_knowledge_layer-0.1.0 → org_knowledge_layer-0.1.2}/README.md

@@ -5,6 +5,14 @@
 > be broken — plus a command that hands the relevant ones to a coding agent (or a
 > person) **before** they start a task, so the same mistake isn't made twice.
 
+```bash
+pipx install org-knowledge-layer   # the distribution name on PyPI
+okl --help                         # the command, the import package, and the repo are all `okl`
+```
+
+*(PyPI rejects `okl` itself as confusable with the existing `oki`, so only the install
+line differs — everything you type afterwards is `okl`.)*
+
 ## The problem it solves
 
 A team (or an AI agent) fixes a subtle bug, learns *why* it happened, and writes a
@@ -184,18 +192,18 @@ knowledge. The switch is one environment variable; none of your commands change.
 ## Install
 
 ```bash
-pipx install okl            # once it's published; for now:
-pip install -e .            # from this repo
+pipx install org-knowledge-layer   # provides the `okl` command
+pip install -e .                   # or from a clone of this repo
 ```
 
 The core (local + client + CLI) is **stdlib-only** — zero required dependencies.
 Extras are opt-in:
 
 ```bash
-pip install "okl[service]"    # FastAPI shared service
-pip install "okl[postgres]"   # Postgres backend (psycopg)
-pip install "okl[mcp]"        # MCP server for Claude Code / Cursor / Copilot
-pip install "okl[all]"
+pip install "org-knowledge-layer[service]"    # FastAPI shared service
+pip install "org-knowledge-layer[postgres]"   # Postgres backend (psycopg)
+pip install "org-knowledge-layer[mcp]"        # MCP server for Claude Code / Cursor / Copilot
+pip install "org-knowledge-layer[all]"
 ```
 
 ## Wire a repo
@@ -371,19 +379,23 @@ okl serve --port 8080
 ## Run the shared service
 
 ```bash
-pip install "okl[service]"
+pip install "org-knowledge-layer[service]"
 OKL_DATABASE_URL="sqlite:///okl.db" OKL_TOKEN="a-shared-secret" okl serve
 # repos then: okl connect https://your-host --token a-shared-secret
 ```
 
-`OKL_TOKEN` (optional) gates **writes**; reads stay open. Deploy the service
+`OKL_TOKEN` (optional) gates **writes**; **reads stay open** — `/nodes` returns the
+whole store to anyone who can reach the port. A mature store holds your defect history,
+security patterns and internal architecture, so treat it as sensitive: bind it to a
+private network or put authentication in front of every route before exposing it. See
+[SECURITY.md](SECURITY.md). Deploy the service
 wherever you like — it's storage-agnostic by design (a `Dockerfile` and a
 `fly.toml` are the obvious next commit; not included in v0).
 
 ## Agent integration (MCP)
 
 ```bash
-pip install "okl[mcp]"
+pip install "org-knowledge-layer[mcp]"
 okl mcp     # register in your coding agent's tool config
 ```
 
@@ -434,10 +446,16 @@ tests/            # end-to-end tests
 ## Test
 
 ```bash
-pip install "okl[dev]"
+pip install "org-knowledge-layer[dev]"
 pytest -q          # full suite (one drift test self-skips where git init is unavailable)
 ```
 
 ## License
 
 MIT.
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for setup, the repo's own rules (mirror files,
+drift, evidence-based verification), and where help is most useful. Security policy and
+the deployment threat model: [SECURITY.md](SECURITY.md).

org_knowledge_layer-0.1.2/SECURITY.md

@@ -0,0 +1,56 @@
+# Security
+
+## Reporting a vulnerability
+
+Please report privately via GitHub's **Report a vulnerability** button on the
+[Security tab](https://github.com/emeraldleaf/okl/security), not in a public issue.
+Expect an acknowledgement within a week. This is a v0 project maintained by one person;
+fixes are best-effort, and the honest expectation is a patch release or a documented
+mitigation, not a same-day turnaround.
+
+Supported: the latest `0.1.x` release. Older versions get nothing.
+
+## What this software does that you should know about
+
+Three behaviors are deliberate, not bugs. If any of them is wrong for your environment,
+that is a configuration decision you need to make before deploying.
+
+### 1. The shared service leaves reads unauthenticated by default
+
+`okl serve` gates **writes** behind `OKL_TOKEN` when that variable is set. **Reads are
+always open**: `/check`, `/search`, `/nodes`, `/metric/recurrence` and `/health` require
+no credential. `/nodes` returns the entire store.
+
+That matters because of what a mature store contains: your defect history, the security
+mistakes you have already made, internal architecture decisions, retired identifiers,
+and the shape of your systems. **Treat the store as sensitive** and assume anyone who
+can reach the port can read all of it.
+
+If you deploy it beyond localhost:
+
+- put it behind a reverse proxy that enforces authentication on every route, or bind it
+  to a private network;
+- terminate TLS upstream (the app speaks plain HTTP and has no certificate handling);
+- set `OKL_TOKEN` so writes are not anonymous;
+- expect no rate limiting, no audit log of reads, and no per-user access control.
+
+### 2. `okl verify --run` executes a shell command by design
+
+The verification command runs whatever you pass to `--run` through a shell, reads the
+real exit status, and records the command as evidence. That is the feature: verification
+must come from an executed check. It also means **never pass untrusted input to
+`--run`**, and never wire it to a command built from unreviewed data.
+
+### 3. The hooks execute scripts from your repository
+
+`okl init` installs shell hooks into `.claude/hooks/` and registers them. They run
+whenever your agent runs. Read them before installing, the same as any other hook, and
+review changes to them the same way you would review CI configuration.
+
+## What ships in the package
+
+The published distribution includes seed data: real engineering rules, architecture
+decisions, and defect classes from the author's own projects, with project identities
+genericized. It contains no credentials, no customer data, and no third-party code.
+The scaffold deliberately does not vendor other people's skills; see
+`RECOMMENDED-COMPANIONS.md` in the kit for what it points at instead.

org_knowledge_layer-0.1.2/docs/ab-results-chart.svg

@@ -0,0 +1,27 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="1200" height="1200" viewBox="0 0 1200 1200" font-family="Helvetica Neue, Helvetica, Arial, sans-serif">
+  <rect width="1200" height="1200" fill="#fcfcfb"/>
+
+  <text x="600" y="136" font-size="46" fill="#52514e" text-anchor="middle">Known defects in agent-written code</text>
+
+  <text x="288" y="430" font-size="210" font-weight="700" fill="#2a78d6" text-anchor="middle">33%</text>
+  <text x="600" y="414" font-size="130" fill="#a8a7a1" text-anchor="middle">→</text>
+  <text x="912" y="430" font-size="210" font-weight="700" fill="#eb6834" text-anchor="middle">4%</text>
+
+  <text x="288" y="504" font-size="41" fill="#0b0b0b" text-anchor="middle">rules written down</text>
+  <text x="288" y="554" font-size="41" fill="#0b0b0b" text-anchor="middle">but not delivered</text>
+  <text x="912" y="504" font-size="41" fill="#0b0b0b" text-anchor="middle">rules retrieved into</text>
+  <text x="912" y="554" font-size="41" fill="#0b0b0b" text-anchor="middle">context, every task</text>
+
+  <line x1="140" y1="644" x2="1060" y2="644" stroke="#e6e5e1" stroke-width="1"/>
+
+  <text x="600" y="722" font-size="43" fill="#0b0b0b" text-anchor="middle">Same model, same tasks. The only difference:</text>
+  <text x="600" y="776" font-size="43" fill="#0b0b0b" text-anchor="middle">whether anything put them in front of the agent.</text>
+
+  <rect x="140" y="842" width="920" height="164" rx="16" fill="#f4f3f0"/>
+  <text x="600" y="908" font-size="41" fill="#0b0b0b" text-anchor="middle">A budget model with the rules (12%) beat</text>
+  <text x="600" y="960" font-size="41" fill="#0b0b0b" text-anchor="middle">a frontier model without them (33%).</text>
+
+  <text x="600" y="1072" font-size="26" fill="#82817c" text-anchor="middle">8 tasks, 3 samples per arm, graded blind by a second, different model.</text>
+  <text x="600" y="1110" font-size="26" fill="#82817c" text-anchor="middle">Measures defect classes the store covers, not general code quality. Small n.</text>
+  <text x="600" y="1152" font-size="26" fill="#82817c" text-anchor="middle">Method and receipts: github.com/emeraldleaf/okl</text>
+</svg>

org_knowledge_layer-0.1.2/docs/posts/01-memory-that-outlives-the-run.md

@@ -0,0 +1,65 @@
+# Memory that outlives the run
+
+*Part 1 of 3: The loop that learns. How one developer's AI loop remembers, verifies, and enforces.*
+
+An agent writing code in one of my repos has no access to what the others learned. That is the problem in one sentence, and better prompting does not solve it.
+
+Every project I work in has an instructions file with real standards in it. But a rule in a prompt is a suggestion, not a control: sometimes the agent applies it, sometimes I restate it, and neither of those is a system. Corrections do not persist either. A fix made in review is scoped to one conversation. The next session starts clean, and the next repository starts cleaner.
+
+## What the audit actually found
+
+So I audited my own setup across three codebases: a .NET microservices platform, a geospatial ML pipeline, a Python RAG service. The question was not whether the code was good, it was whether the standards I had written down were reaching the work.
+
+Two findings.
+
+First, several rules I had documented as enforcement were enforcement in name only. In one repo an architecture-review agent was described across six documents as a live review surface; nothing in CI or in any hook actually invoked it. Every one of those documents was accurate about the design and wrong about the system. Writing a rule down and running it are different acts, and only one of them changes what ships.
+
+Second, and worse: the three repos had independently derived the same rules. Each had paid separately for knowledge the others already had. My standards existed, they were even written down, and they still could not cross a repository boundary. I had been thinking of my setup as "two readers, one canon": a human reads the rules, an agent reads the rules, and the two must not drift. What I actually had was N readers and N canons.
+
+## The fix is a layer, not a bigger prompt
+
+The obvious move is to paste every standard into every prompt. That fails in a specific way: always-on context taxes every session whether the rule is relevant or not. My .NET repo enforces a hard size budget on its instructions file in CI, warning at 400 lines and failing the build at 500, precisely because every byte of always-on context costs both readers attention.
+
+So the design question became: where does each piece of knowledge belong? Three questions, asked in order.
+
+**Does a session doing a completely unrelated task still need this?** Then it belongs in the always-on instructions. Almost nothing passes. Naming conventions, the security posture, the error-handling canon. This is the most expensive real estate in the system and the size budget is what keeps it honest.
+
+**Would I want this in front of me whenever a future task resembles it?** Then it belongs in a retrievable store. This is the large category: the rate-limiter rule that matters enormously to the three tasks a year touching rate limiting, and is noise for everything else.
+
+**Does it stop mattering once the PR merges?** Then it stays with the task. The subtle part is extraction, because a dead plan usually contains one durable decision worth pulling out before the rest is discarded.
+
+The middle tier is the part I had to build: a small typed store of what the projects already know. Defects with symptom, cause, and fix. Rules. Deliberate decisions, recorded so they are not silently reversed. Tombstones for identifiers that must never come back. Retractions for claims that turned out to be false. Every note carries a scope, because org-wide standards should propagate to every project while one repo's quirks should stay home. Choosing that scope is a judgment call and it is the curation step that keeps a shared layer from filling with noise.
+
+## Retrieved, not loaded
+
+The reason the store can grow indefinitely is that no session ever reads it. Before a task starts, a hook queries it with the task description and injects only what survives four filters: relevance ranking, scope, the declared subject interests of the current repo, and typed routing that turns the survivors into a short action list. Fix this. Run that gate. Do not restate this retracted claim.
+
+Each run sees a dozen relevant lines rather than the whole library. At ten times the current corpus, what reaches the agent should be the same length and better chosen.
+
+## None of this is a new idea
+
+Agent memory is one of the most crowded categories in the field: mem0, Zep, Letta and Cognee on the infrastructure side, Cursor Memories and Devin Knowledge built into the coding agents, AGENTS.md and CLAUDE.md as the convention nearly everyone already uses. "Give the agent your team's knowledge" is the consensus position, not an insight, and if semantic recall over what an agent has seen is the problem you have, those tools are better at it than anything I would build.
+
+The gap I kept hitting was invalidation. Every one of those systems accumulates: records get added, ranked, retrieved. None of them knows that a rule went stale because the code it governs moved on without it. So the bet here is narrow and specific, and it is the subject of part 2: a rule cites the source it governs, carries a verification receipt, decays on a clock, and fails CI when the code changes after the rule was last checked. Records treated like tests, not like notes.
+
+## Proving it does something
+
+A tool that feels helpful and a tool that is helpful are different claims, so I built an A/B harness and committed the results.
+
+Eight tasks, each written to invite a specific defect class the store already covers. The same model in both arms, the retrieved rules as the only variable. A second, different model grading blind, never told which arm produced the code. Failure counts printed before any score, because a metric that cannot report its own failure rate is not a metric.
+
+With none of the rules in context, the agent reproduced a known defect class in 33 percent of runs. With them, 4 percent. On the tasks the baseline actually failed, runs with the rules in context reproduced the defect in 1 of 15. One task, an unpinned linter version in CI, failed three times out of three without the rules and never with them.
+
+The result I did not expect: a budget model with the rules in context made roughly a third the known mistakes of a frontier model without them on identical tasks. Context bought more than the model upgrade did, which is the more useful number if you are routing work between cheap and expensive models.
+
+## The limits, stated
+
+Those tasks were authored from rules already in my own store, so the experiment measures prevention of defect classes the store covers rather than general code quality. Small n. Directional, not a benchmark. The full method and every receipt are in the repository, including the runs that went the other way.
+
+The system also found its own first defect: an early retrieval marked 28 of 33 stored notes as relevant to a single task. Ranking put the right records first, but nothing trimmed the tail. Subject tags and per-repo interest declarations cut it to 20; a proper relevance cutoff is still open work, recorded in the store as a defect against the store. The failure log lives inside the system it describes.
+
+That is the first idea. The state in most agent-loop diagrams lives inside one execution. The compounding win is memory that outlives it: record the rule once, retrieve it into every future task that resembles it, across every project. Run N+1 should not repeat run N's mistake, and neither should the next repository.
+
+Next: the verify step, and why a step's own report of success is not evidence.
+
+*The model generates. The loop governs. The standard holds.*

org_knowledge_layer-0.1.2/docs/posts/02-dont-let-a-step-grade-itself.md

@@ -0,0 +1,45 @@
+# Don't let a step grade itself
+
+*Part 2 of 3: The loop that learns. How one developer's AI loop remembers, verifies, and enforces.*
+
+Never trust an exit code. This is the incident behind that rule.
+
+A pipeline step was supposed to materialize 238 files. It produced none. Every window raised, the exceptions were swallowed inside a worker pool, and the process exited zero. Downstream steps ran happily against an empty directory. The fix was trivial once seen: count the outputs rather than read the exit status. The discipline it bought has outlasted the project: a step reporting success and the work being done are two different facts, and only one of them is evidence.
+
+That rule matters more when an agent is writing the steps. Review catches things, but review is sampling. What makes generated code safe at volume is the checks that run whether or not anyone is paying attention, and those checks are only as good as the question they actually ask.
+
+## The same bug wears several costumes
+
+A dependency's major-version upgrade compiled clean and carried three runtime breaking changes, one of which silently broke transactional atomicity. The build was green. Green answered "does this compile," which was not the question anyone cared about.
+
+In an eval harness, an LLM judge printed a perfect 5.0 out of 5.0 while 19 of 20 cases had crashed, because it averaged the survivors. The score was real. It was also meaningless, and nothing in the output said so.
+
+Different costumes, same failure: the verifier reported on itself, and the report was wrong.
+
+## The grader is usually ls, not an LLM
+
+When I say don't let a step grade itself, people sometimes hear "put a second model in front of every step." Almost never. The correct grader for the 238-file failure was a file count. The correct grader for the upgrade was an integration test that forced a rollback and asserted no event escaped. Boring, deterministic checks, placed at the boundaries where the loop makes a decision: mark done, merge, deploy.
+
+A second model earns its place in exactly one case: when the verify signal is itself a judgment, like scoring summary quality or reviewing generated code. Only there does judge-must-differ-from-generator apply, because a judgment shares blind spots with whoever produced it. A file count has no blind spots.
+
+## Four rungs of independence
+
+In the knowledge layer from part 1, verification is not one feature. It is four rungs, each answering the same question while trusting the claimant less.
+
+**Rung 1: assertion, quarantined.** A "verified" flag that whoever writes the record can set is a step grading itself. The flag still exists, but only for importing historical receipts. Live verification refuses it.
+
+**Rung 2: an observed check with a stored evidence trail.** The verify command takes a record and a check to run. It runs the check, reads the real exit status, and when you name an expected success signal it requires that signal in the output, because exit zero alone is precisely what failed on those 238 files. Only an observed pass stamps the record, and the command, result, and timestamp are stored on the record itself. The claimant still chooses the check, and a weak check is still possible, but the stamp shows exactly which check ran. "Verified by: true" is visible to every future reader and invites the obvious question. Assertion hides its emptiness; evidence exposes it.
+
+**Rung 3: an independent actor re-runs the checks.** CI runs the drift gate and the repository's mechanical gates on every pull request: a different grader, at a different time, with no stake in the original claim. When a gate proves itself by failing against real drift, the receipt is written by the job that watched it happen, not by the gate's author.
+
+**Rung 4: time attacks every stamp.** Each rule declares the files it governs. The moment those files change after the rule was last verified, the drift detector flags it, because a stale rule is a rule nobody re-checked. Verification also decays on a clock: a stamp nobody re-earns is demoted rather than left quietly trusted. And the system is scored on an outcome it cannot flatter itself on: recurrence after arming, the count of defect classes that came back even though a catching check existed. Not "how many rules were recorded," which measures activity, but "did the mistakes stop repeating," which measures the point.
+
+## Where judgment stays
+
+The remaining self-grading surface is check selection. Nothing stops someone from verifying a record against a trivially weak check. I left that to human judgment deliberately and made it inspectable instead of trying to mechanize taste: every stamp displays its evidence, so a weak check becomes a visible artifact rather than an invisible belief. Mechanize what can be mechanized, audit the rest.
+
+One detail worth the build: the rule stating that verification comes from observed checks and never from assertion lives in the store as a record, and it was the first record verified by the verify command itself, evidence trail and all. The system's rules are subject to the system.
+
+Next: enforcement, and why a rule that is not wired to something that runs is a preference.
+
+*The model generates. The loop governs. The standard holds.*

org_knowledge_layer-0.1.2/docs/posts/03-enforcement-or-good-intentions.md

@@ -0,0 +1,37 @@
+# Enforcement, or good intentions
+
+*Part 3 of 3: The loop that learns. How one developer's AI loop remembers, verifies, and enforces.*
+
+A rule that is not wired to something that runs is a preference, not a standard.
+
+I know that from auditing my own work. In one codebase an architecture-review agent was documented across six files as a live enforcement surface. When I audited what actually executed, meaning the CI jobs, the hooks, and the pre-commit path, that agent appeared nowhere. Every one of those documents was accurate about the design and wrong about the system.
+
+I have now found the same shape in three codebases, which makes it a pattern rather than an oversight: if a rule only lives in the prompt, sometimes the agent applies it, sometimes I restate it, and neither of those is a control. Probabilistic compliance is still non-compliance when the point is a guarantee.
+
+## What mechanical looks like
+
+In the loop from parts 1 and 2, every rule that matters is wired to something that runs without anyone deciding to run it.
+
+**The read is enforced, fail closed.** The moment a task is submitted, a hook retrieves the relevant rules and decisions and injects them into the model's context before any work begins. If the store is unreachable, the hook blocks the task rather than proceeding, because "nothing applies here" and "I could not reach the store" look identical from the outside and only one of them is safe. Silence is never reported as safety. There is an explicit override for working offline, explicit on purpose: proceeding without the standards should be a decision someone made, not a default they fell into.
+
+One detail that cost me a rebuild. The first version was wired to an event whose output the model never receives. The hook fired on every edit, retrieved exactly the right rules, and wrote them to a channel nothing read, while every unit test passed, because those tests proved the hook ran and produced correct text. Only a behavioral test against a bare control repository exposed it: same task, same model, defect reproduced in both arms. A hook that fires is not a hook that is heard. Test the channel, not the firing.
+
+**The write is prompted at the only moment it can work.** What a session learns dies with it, so a stop hook blocks the first stop of any session that changed files and asks one question: did this session produce something worth keeping? Either it is recorded with a deliberate scope and subject, or the session states that nothing durable came out of it and finishes. It fires once per session and never loops. The first session running that hook was caught by it and had to record three rules it had applied but never encoded. A rule that catches its own author on day one is at least running.
+
+**The gates run at merge time.** Retired identifiers cannot resurface. Retracted claims cannot be restated. Documentation cannot silently orphan. The instructions file cannot bloat past its budget. Each is a small script that fails CI, and none of them require anyone to remember anything.
+
+## Installation is where enforcement quietly dies
+
+Auditing my own installer turned up the same failure one layer down: it did half the wiring and printed instructions for the rest. Install the hook, then "add it to your settings file." Copy this CI workflow. Register this tool. Four printed instructions, four surfaces that would never run for anyone who skipped the homework, which over time is everyone including me.
+
+So the rule became: init must wire, not instruct. It registers the hooks in the agent's settings itself, idempotently, preserving whatever is already there. It installs the CI workflow instead of describing it. It registers the agent tools when the dependency exists and deliberately refuses when it does not, because a registration pointing at a missing dependency is a broken tool, which is worse than none. The only things it prints are the things it genuinely cannot do, and it says those loudly: this is not a git repository, so the drift gate is disabled until it is.
+
+The same failure again at the environment layer. Hooks run in whatever process the agent harness spawns, which routinely lacks the PATH of the shell you developed in. A hook that works on the author's machine and silently no-ops on everyone else's is the "surface nobody runs" bug wearing an environment-variable costume. The fix is a layered resolver: an explicit override, then a path pinned at install time by the shell where the tool demonstrably works, then PATH, then module execution by any interpreter that can import the package. The enforcement hook fails closed with instructions when nothing resolves; the reminder hook silently disables, because a best-effort prompt must never brick someone's session. Degrade by role.
+
+## Where the trust boundary sits
+
+The stop hook can be lied to. A session can answer "nothing durable" untruthfully and finish. I left that boundary deliberately, the same way a ship-moment reminder is a reminder and not a block: the mechanical part is putting the question in front of you at the right moment, every time. Answering it honestly stays a person's job. The aim is not to remove judgment, it is to guarantee judgment gets exercised at the moments that matter, with the relevant evidence already in view.
+
+That is the series. Memory that outlives the run, verification that does not trust a step's own report, and enforcement that runs without being remembered. None of the three is exotic alone. The compounding comes from wiring them together: the enforced read puts the standard in front of the agent, the verification rungs keep the standard honest, and the recurrence metric reports whether any of it worked, in the only currency that counts: mistakes that stopped repeating.
+
+*The model generates. The loop governs. The standard holds.*

{org_knowledge_layer-0.1.0 → org_knowledge_layer-0.1.2}/evals/REPORT.md

@@ -13,6 +13,12 @@ cheaper model perform at or above an unbriefed frontier model on those defect cl
 
 ## 2. How to read these numbers
 
+**On the word "briefed."** The two arms are named `baseline` and `briefed` in the
+committed result files, so this report uses those names to stay aligned with the data.
+Mechanically, *briefed* means: before generation, the relevant past lessons were
+retrieved from the store, filtered by scope and subject, and placed in the model's
+context. Nothing else differs between the arms.
+
 **A "run" is one complete attempt:** the generator gets one task (with or without the
 briefing) and produces code; the blind judge then answers one question — does this code
 contain the specific known mistake this task was designed to invite?

{org_knowledge_layer-0.1.0 → org_knowledge_layer-0.1.2}/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.1.0"
+version = "0.1.2"
 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.1.0 → org_knowledge_layer-0.1.2}/seed/react-defects.json

@@ -1,5 +1,5 @@
 {
- "_comment": "Seed for the OKL — React/frontend-SPA lessons ported from the .NET platform's frontend canon (frontend/CLAUDE.md + the vendored vercel-react-best-practices skill, frozen 2026-06-12). React is backend-agnostic, so these are org-scoped: they propagate to any repo with a React UI. This closes the coverage gap the A/B experiment measured — react_fetch reproduced the useEffect-fetching defect 3/3 in BOTH arms because no React node existed in the store to inject.",
+ "_comment": "Seed for the OKL — React/frontend-SPA lessons ported from the author's own frontend canon (frontend/CLAUDE.md, frozen 2026-06-12); external guides are cited in found_by as provenance, not reproduced. React is backend-agnostic, so these are org-scoped: they propagate to any repo with a React UI. This closes the coverage gap the A/B experiment measured — react_fetch reproduced the useEffect-fetching defect 3/3 in BOTH arms because no React node existed in the store to inject.",
  "nodes": [
   {
    "key": "rx_useeffect_fetch",

{org_knowledge_layer-0.1.0 → org_knowledge_layer-0.1.2}/src/okl/scaffold/profiles/react/README.md

@@ -14,5 +14,5 @@ Installed to `.claude/rules/`:
   (BFF trade-off documented), MSW + Playwright testing.
 
 Reference stack: Vite + React 19 + TS strict, CSR SPA, TanStack Query/Router, Zustand, Tailwind v4 +
-shadcn/ui, oidc-client-ts → Keycloak. Deep reference: the vendored `vercel-react-best-practices`
+shadcn/ui, oidc-client-ts → Keycloak. These rules are original to this kit; pair them with any external React guide
 skill (70 rules), where the canon wins on any disagreement.

{org_knowledge_layer-0.1.0 → org_knowledge_layer-0.1.2}/src/okl/scaffold/profiles/react/rules/frontend.md

@@ -9,8 +9,8 @@ paths: ["frontend/**/*.tsx", "frontend/**/*.ts", "**/frontend/**/*.tsx", "**/fro
 > storefront) — but backend-agnostic: stack these onto ANY backend profile (dotnet, python-rag, …)
 > whose repo has a React frontend. Reference stack: Vite + React 19 + TypeScript (strict), CSR SPA;
 > TanStack Query v5 + Router; Zustand (small UI globals only); Tailwind v4 + shadcn/ui; oidc-client-ts
-> → Keycloak (auth-code + PKCE); React Compiler on. Deep reference: the vendored
-> `vercel-react-best-practices` skill (70 rules) — **but this canon wins where they disagree.**
+> → Keycloak (auth-code + PKCE); React Compiler on. These rules are original to this kit;
+> where you also consult an external React best-practices guide, **this canon wins where they disagree.**
 >
 > Where a rule cites "the backend" (VSA feature folders, server-controlled fields, cache-in-write-path,
 > measure-before-optimizing), the parallel holds against whatever backend you pair this with.

org_knowledge_layer-0.1.0/docs/posts/01-memory-that-outlives-the-run.md

@@ -1,43 +0,0 @@
-# Memory that outlives the run
-
-*Part 1 of 3: The loop that learns. How our AI dev loop remembers, verifies, and enforces.*
-
-I noticed something embarrassing while auditing three of my own codebases: they had all learned the same lesson, separately, the hard way.
-
-One is a .NET microservices platform. One is a geospatial ML pipeline. One is a Python RAG service. In each of them, at some point, I had built a review rule or a checklist, described it in the docs as a live enforcement surface, and then discovered months later that nothing had ever run it. Three repos, three independent discoveries, one lesson: a surface nobody runs is documentation, not enforcement.
-
-The lesson wasn't the embarrassing part. The embarrassing part was the *three times*. Each repo had a careful CLAUDE.md, encoded rules, a real engineering method. And none of that knowledge could cross the repo boundary. Every project was re-deriving the org's hard-won lessons from scratch, one incident at a time.
-
-I had been thinking of my setup as "two readers, one canon": a human reads the rules, an AI agent reads the rules, and the two must not drift apart. What I actually had was N readers and N canons.
-
-## The fix is a layer, not a bigger prompt
-
-The obvious move is to paste every lesson into every prompt. That fails fast, and it fails in a specific way: always-on context taxes every session whether the lesson is relevant or not. My .NET repo enforces a hard size budget on its instructions file in CI (warning at 400 lines, build failure at 500) precisely because every byte of always-on context is cognitive overhead for both readers.
-
-So the design question became: where does each piece of knowledge belong? I ended up with a three-way triage, decided by three questions asked in order.
-
-**Does a session doing a totally unrelated task still need this?** Then it goes in the always-on instructions. Almost nothing passes this test. Naming conventions, the security posture, the error-handling canon. This is the most expensive real estate in the system, and the CI size budget keeps it honest.
-
-**Would I want this to appear whenever a future task resembles it?** Then it goes in the knowledge store. This is the interesting category: the rate-limiter lesson that matters enormously to the three tasks a year that touch rate limiting, and is pure noise for everything else.
-
-**Does it stop mattering once the PR merges?** Then it stays with the task and is allowed to die. The subtle part is extraction: a dead plan often contains one durable decision worth pulling out before you let go of the rest.
-
-The store is the part I had to build. It's a small typed database of lessons: defects with symptom, cause, and fix. Rules. Deliberate decisions, so they don't get silently reversed. Tombstones for identifiers that must never come back. Retractions for claims that turned out to be false. Each note carries a scope: org-wide lessons propagate to every connected repo, repo-scoped quirks stay home. Choosing that scope is a human judgment, and it's what keeps a shared layer from filling up with one project's noise.
-
-## Retrieved, not loaded
-
-The reason the store can grow forever is that no run ever reads it. Before a task starts, a hook searches the store with the task description and injects only what survives four filters: lexical relevance ranking, scope (another repo's quirks are structurally invisible), declared interests (my Python repo says it cares about eval integrity and retrieval design, so React lessons never appear no matter how well they match), and typed routing that turns the survivors into a short action list. Fix this, run that gate, don't restate this retracted claim.
-
-Each run sees a dozen relevant lines, not the whole library. At ten times the current size the briefing should be the same length, just better chosen.
-
-Does it work? I measured it the way I'd measure anything: a held-fixed A/B, same model both arms, briefing injected versus not, scored by a blind judge that was deliberately a different model from the generator. In the original experiment, defect reproduction on covered tasks dropped from 50 percent to 6 percent, and from 75 percent to 8 percent on the tasks where the baseline model actually failed. I later rebuilt that experiment as a checked-in harness anyone can re-run, and the fresh receipt (48 sampled runs, zero harness failures) tells a sharper story: today's stronger models dodge much of the bait unaided, but the baseline still reproduced known defect classes in 33 percent of runs, and the briefed arm in 4 percent. On the tasks the baseline failed at least once, briefed runs reproduced in 1 of 15. One task always failed unaided, three out of three, and never failed briefed. The value concentrates exactly where models still get things wrong, which is exactly what an org's hard-won lessons describe. And the misses in the original run were both coverage gaps, a lesson not yet in the store, so the check doubles as a detector for what to encode next.
-
-## The honest part
-
-The first real dogfood run also found the system's first defect, in itself: the briefing for one specific task marked 28 of the 33 stored notes as relevant. Ranking put the right lessons first, but nothing cut the tail. Subject tags plus per-repo interest declarations cut it to 20 of 33, and a proper relevance cutoff is still open work, recorded in the store as a defect against the store, status: narrowed. The system's failure log lives inside the system.
-
-That's the whole first idea. The state in most loop diagrams only lives inside one execution. The compounding win is memory that outlives the run: record the lesson once, retrieve it into every future task that resembles it, across every repo. Run N+1 should never repeat run N's mistake.
-
-Next up: the verify step, and why you should never let a step grade itself.
-
-*The model generates, the loop governs, and the team learns.*

org_knowledge_layer-0.1.0/docs/posts/02-dont-let-a-step-grade-itself.md

@@ -1,37 +0,0 @@
-# Don't let a step grade itself
-
-*Part 2 of 3: The loop that learns. How our AI dev loop remembers, verifies, and enforces.*
-
-I had a pipeline step whose job was to write 238 files. It failed on every single one, swallowed the exceptions inside a worker pool, and exited with a success code. Everything downstream ran happily on an empty folder. By the time I noticed, I was debugging the wrong end of the pipeline.
-
-That incident bought me a rule I now apply everywhere: a step saying it succeeded and the work actually being done are two different facts, and the loop has to check the second one. Exit codes, green builds, and tests passing on invented fixtures all answer a narrower question than the one the loop thinks it's asking.
-
-The same class of failure, in fancier clothes: a dependency's major-version upgrade compiled clean and carried three runtime breaking changes, one of which silently broke transactional atomicity. And in an eval harness, my LLM judge printed a perfect 5.0 out of 5.0 while 19 of 20 cases had crashed, because it averaged only the survivors. Different costumes, same bug. The verifier reported on itself, and the report was wrong.
-
-## The grader is usually ls, not an LLM
-
-When I say don't let a step grade itself, people sometimes hear "every step needs a second model reviewing it." Almost never. The correct grader for my 238-file disaster was a file count. The correct grader for the upgrade was an integration test that forced a rollback and asserted no event escaped. Boring, deterministic checks, placed at the boundaries where the loop makes a decision: mark done, merge, deploy.
-
-A second model enters in exactly one case: when the verify signal is itself a model's judgment, like grading summary quality or reviewing generated code. Only there does judge-must-differ-from-generator apply, because a judgment shares blind spots with whoever produced it. A file count has no blind spots.
-
-## Four rungs of independence
-
-In the knowledge layer I described in part 1, verification isn't one feature. It's four escalating rungs, each answering the same question with less trust in the claimant.
-
-**Rung 1: assertion, quarantined.** A "verified" flag that whoever writes the record can set is a step grading itself. The system still has that flag, but only for importing historical receipts. Live verification refuses it.
-
-**Rung 2: an observed check with a stored evidence trail.** The verify command takes a node and a check to run. It runs the check itself, reads the real exit code, and, if you name an expected success signal, requires that signal to appear in the output, because exit zero alone is exactly what burned me on those 238 files. Only on an observed pass does it stamp the record, and it stores the command, the result, and the timestamp on the record itself. Yes, the claimant still chooses the check, and a lazy check is still possible. But the stamp records exactly which check was run. "Verified by: true" is visible to every future reader and invites the obvious question. Assertion hides its emptiness; evidence exposes it.
-
-**Rung 3: an independent actor re-runs the checks.** CI runs the drift gate and the repo's mechanical gates on every pull request. A different grader, at a different time, with no stake in the original claim. When a gate proves itself by actually failing against real drift, the receipt is written by the job that watched it happen, not by the gate's author.
-
-**Rung 4: time attacks every stamp.** Each rule declares which files it governs. The moment those files change after the rule was last verified, the drift detector flags it: a stale rule is a rule nobody re-checked. Verification also decays on a clock; a stamp nobody re-earns demotes to stale rather than staying quietly trusted. And the whole system is scored on an outcome it cannot flatter itself on: recurrence after arming, the count of defect classes that came back even though a catching check existed. Not "how many lessons did we record," which measures activity, but "did the mistakes stop repeating," which measures the point.
-
-## The honest part
-
-The remaining self-grading surface is check selection. Nothing stops someone from verifying a record against a trivially weak check. I chose to leave that to human judgment and make it inspectable rather than trying to mechanize taste: every stamp shows its evidence, and a weak check is now a visible, embarrassing artifact instead of an invisible belief. Mechanize what can be mechanized. Make the rest auditable.
-
-One detail I enjoy: the rule that says "verification stamps come from observed checks, never from assertion" lives in the store as a record, and it was the first record verified by the verify command itself, evidence trail and all. The system's rules are subject to the system.
-
-Next up: enforcement, and why a checklist nobody is forced to run is documentation.
-
-*The model generates, the loop governs, and the team learns.*

org_knowledge_layer-0.1.0/docs/posts/03-enforcement-or-good-intentions.md

@@ -1,33 +0,0 @@
-# Enforcement, or good intentions
-
-*Part 3 of 3: The loop that learns. How our AI dev loop remembers, verifies, and enforces.*
-
-The most instructive bug in my method wasn't in code. It was in the documentation of an agent that reviewed architecture. Six separate documents described it as a live enforcement surface. It had been invoked by nothing, ever. Every one of those documents was telling the truth about the design and lying about the system.
-
-I have now learned this lesson in three different codebases, which is what finally made it stick: if a rule only lives in the prompt, sometimes the agent picks it up on its own, sometimes I have to remind it, and neither of those is a system. Probabilistic compliance from a model is still non-compliance from a control standpoint. Enforcement has to be mechanical or it's just good intentions.
-
-## What mechanical looks like
-
-In the loop I've been describing across this series, every rule that matters is wired to something that runs without anyone deciding to run it.
-
-**The read is enforced, fail closed.** The moment a task is submitted, a hook retrieves the relevant lessons from the knowledge store and injects them into the model's context, before any work begins. If the store is unreachable, the hook blocks the task instead of proceeding, because "no lessons apply" and "I couldn't reach the lessons" look identical from the outside and only one of them is safe. Silence is never reported as safety. There's an explicit override for working offline, and it's explicit on purpose: proceeding blind should be a decision someone made, not a default someone fell into. One hard-won detail: my first version wired this to the wrong event, one whose output the model never sees. The hook fired on every edit, retrieved the right lessons, and printed them into a void, while every unit test passed. Only a behavioral test against a bare control repo exposed it. A hook that fires is not a hook that's heard. Test the channel, not the firing.
-
-**The write is prompted at the only moment it can work.** Lessons die when sessions end, so a stop hook blocks the first stop of any session that changed files and asks one question: did this session learn something worth keeping? Either the lesson gets recorded, with its scope and tags chosen deliberately, or the session states that nothing durable was learned and finishes. It fires once per session and never loops. The first session running that hook got caught by it and had to record three lessons it had fixed but never encoded. The hook worked on its own author, which is the only referee a rule like this will accept.
-
-**The gates run at merge time.** Retired identifiers can't resurface, retracted claims can't be restated, docs can't silently orphan, the instructions file can't bloat past its budget. Each is a small script that fails CI. None of them require anyone to remember anything.
-
-## Installation is where enforcement quietly dies
-
-Here's the failure mode I only caught by auditing my own installer: it did half the wiring and printed instructions for the rest. Install the hook, then "add it to your settings file." Copy this CI workflow. Register this tool. Four printed instructions, four surfaces that would never run for anyone who didn't do the homework, which over time is everyone.
-
-So the installer's rule became: init must wire, not instruct. It registers the hooks in the agent's settings itself, idempotently, preserving whatever else is there. It installs the CI workflow instead of describing it. It registers the agent tools when the dependency exists, and deliberately refuses when it doesn't, because a registration pointing at a missing dependency is a broken tool, which is worse than none. The only things it's allowed to print are the things it genuinely cannot do, and it says those loudly: this isn't a git repository, so the drift layer is disabled until it is.
-
-One layer deeper, same lesson: hooks run in whatever environment the agent harness spawns, which routinely lacks your dev shell's PATH. A hook that works on the author's machine and silently no-ops on everyone else's is the "surface nobody runs" bug wearing an environment-variables costume. The fix is a layered resolver: an explicit override, then a path pinned at install time by the shell where the tool demonstrably works, then PATH, then module execution by any interpreter that can import the package. The enforcement hook fails closed with instructions when nothing resolves; the reminder hook silently disables, because a best-effort prompt must never brick someone's sessions. Degrade by role.
-
-## The honest part
-
-The stop hook can be lied to. A session can answer "nothing durable learned" untruthfully and finish. I left that trust boundary in on purpose, the same way the ship-moment reminder in my .NET repo is a reminder and not a block: the mechanical part is putting the question in front of you at the right moment, every time. Answering it honestly stays a human's job. The system's aim isn't to remove judgment. It's to make sure judgment is exercised at the moments it matters, with the relevant evidence in view, instead of whenever someone happens to remember.
-
-That's the series. Memory that outlives the run, verification that doesn't trust the step's own report, and enforcement that runs without being remembered. None of the three is exotic on its own. The compounding comes from wiring them together: the enforced read injects the memory, the verify rungs keep the memory honest, and the recurrence metric tells you whether any of it is working, in the one currency that matters, mistakes that stopped repeating.
-
-*The model generates, the loop governs, and the team learns.*