okf-pro 1.0.0

data/.okf/log.md

@@ -0,0 +1,74 @@
+# Update Log
+
+## 2026-08-17
+
+* **okf-pro 1.0.0.** The prototype checker — carried inside a template
+  repository that was cloned to start a bundle — becomes the fourth gem in this
+  monorepo, entered through the okf plugin seam as `okf pro <cmd>` rather than a
+  repository to fork. It ships no executable: a second entry point would be a
+  second thing the scaffold's wrapper has to recognise, on the one code path
+  where being wrong means a gate waves an edit through.
+
+* **Three doors, and a contract that outranks them.** The same invariants are
+  asked at the agent's tool boundary, at `git commit` against the *staged* tree,
+  and again in CI, because each door sees edits the others structurally cannot.
+  Blocking checks fail closed, feedback checks fail loud, and no check ever fails
+  silent — the clause that shapes the code, since every defect this gem has had
+  failed in the direction of silence
+  ([contract/the-contract](/contract/the-contract.md)). Getting there closed
+  three ways the plugin seam let an unchecked edit through
+  ([seam/three-fail-opens](/seam/three-fail-opens.md)), the case where a shim on
+  `PATH` passes every gate by exit status alone
+  ([seam/identity-not-existence](/seam/identity-not-existence.md)), bundler
+  scoping that switched every gate off inside a bundle that did not name this
+  gem ([seam/bundler-scoping](/seam/bundler-scoping.md)), and the checker
+  breaking its own third clause by reporting clean over checks it never ran
+  ([contract/silent-skips](/contract/silent-skips.md)). The `hook` verb is the
+  one place in this repo where exit 1 is *non-blocking* and 2 is the refusal
+  ([contract/exit-codes](/contract/exit-codes.md)).
+
+* **The CLI answers what is on the board, and writes the shapes with one form.**
+  The prototype's surface was gates and nothing else, so an agent in a seeded
+  bundle rediscovered state by reading raw markdown and reconstructed a line's
+  grammar from the guides on every use. `state`, `board`, `snapshot`,
+  `unverified` and `friction` answer, cheaply and in JSON when the consumer is an
+  agent; `capture`, `promote`, `demote`, `journal open` and `close` write.
+  Writers are additive and targeted, never regenerative — each computes its new
+  text purely, declares the delta it intends, and a conservation guard refuses
+  with nothing written when the actual delta differs in either direction
+  ([design/derivation-that-writes](/design/derivation-that-writes.md)). A name a
+  caller supplies is contained twice over
+  ([contract/containment-directions](/contract/containment-directions.md)).
+
+* **A recorder that neither gates nor lies.** `friction` writes down what was
+  done by hand that a verb could have done, at paths that already run rather than
+  at a new hook event, since `settings.json` is seeded and a registration added
+  there would never reach an adopter through `upgrade`. It refuses nothing and
+  still may not report a zero it did not count
+  ([contract/telemetry-does-not-lie](/contract/telemetry-does-not-lie.md)).
+
+* **`okf pro setup` replaces the template repository.** It writes the bundle and
+  the governance around it, splitting what it may later rewrite from what becomes
+  the adopter's by ownership rather than by subject
+  ([scaffold/ownership-not-subject](/scaffold/ownership-not-subject.md)). It
+  never refuses wholesale ([scaffold/collisions-and-refusals](/scaffold/collisions-and-refusals.md)),
+  and no date ships in the generated tree, because dormancy measures a bundle's
+  age by its oldest journal entry and a shipped entry makes a fresh clone read as
+  an old one ([scaffold/no-date-ships](/scaffold/no-date-ships.md)).
+
+* **The seeded README sells the practice, not the command set.** It is the only
+  file in the generated tree addressed to the owner rather than the agent, and it
+  carries what the skill never will: the exit, the limits, the price, and a week
+  showing the system in use. The offer is that being good at any craft has a
+  shape and you reach it by structuring how you work
+  ([scaffold/the-adopters-manual](/scaffold/the-adopters-manual.md)).
+
+* **The trust policy is the format's, not this gem's.** "Awaiting the owner's
+  read" is derived from OKF v0.2 §5.3's tiers rather than from a truthiness test
+  on `verified:`, across all four call sites at once — they cannot move
+  separately ([trust/read-owed-rule](/trust/read-owed-rule.md)). A
+  `process:`-verified briefing is machine-confirmed and still owes the owner a
+  read. A scalar `verified:` is conformant and unreadable, which is the worst
+  direction to fail in ([trust/scalar-verified](/trust/scalar-verified.md)).
+  `freshness` is gone: `stale_after` is the format's own field, and a second
+  implementation disagreeing by a day was worse than none.

data/.okf/scaffold/collisions-and-refusals.md

@@ -0,0 +1,76 @@
+---
+type: Decision
+title: Setup writes what it can, and refuses exactly one thing
+description: A collision is staged beside the adopter's file rather than refused; a root-level bundle is refused outright, because writing there manufactures an ambiguous layout.
+---
+
+# Never refuse wholesale
+
+A repository that already has a `CLAUDE.md` is the common case, not an error.
+`setup` writes everything it can and stages the rest as `<path>.okf-pro-new`,
+with a printed merge instruction. A stale staged file is **refreshed**, never
+doubled — there is no `.okf-pro-new.okf-pro-new`.
+
+Which files can collide at all is a question of [who owns them](/scaffold/ownership-not-subject.md):
+inside `.okf/` nothing is ever staged, only completed.
+
+# And the one refusal has to ask the question it cites
+
+The refusal names `Audit.ambiguous_layout` as the state it prevents, and for a
+while it did not ask what that finding asks. The finding tests `root_kind` —
+`index.md` **plus** `board.md` or `log.md`, or an `okf_version` in the
+frontmatter. The refusal tested `bundle?`, which is `index.md` alone.
+
+So every Jekyll section, every Hugo directory, every repository with an
+`index.md` README was refused at its first `okf pro setup`, and told to
+`git mv index.md log.md <your dirs> .okf/` — files that have nothing to do with
+OKF, for an ambiguity the audit would never have reported. A first run is the
+one moment an adopter has no reason to trust the tool yet, and this spent that.
+
+**A refusal that cites a finding has to be answering the question that finding
+asks.** Two predicates for one condition is one predicate too many, and the
+looser one always wins the argument by refusing more.
+
+The generated `.gitignore` lists `*.okf-pro-new`, and that line is
+load-bearing: inside `.okf/` those files are invisible to `validate` and `lint`
+because they are not `.md`, so without it they get committed and nothing ever
+says so.
+
+Which is why the merge instruction **reads the adopter's tree rather than
+assuming it**. The closing line used to state flatly that `.gitignore` already
+ignores them, and that was false in the one case where it mattered: when
+`.gitignore` is itself the collision, the adopter's own file stays on disk and
+the template's — the copy carrying the line — is what got staged beside it. A
+report that says "already ignored" about files git is about to commit is the
+same silence one paragraph up, produced by the fix for it.
+
+# The one refusal
+
+A bundle whose root **is** the repository root. Writing `.okf/index.md` beside
+it collides with nothing, so a naive generator succeeds — and leaves two bundle
+roots in one directory, which is exactly the state `Audit.ambiguous_layout`
+exists to report, where the three doors disagree until one of the two is
+retired.
+
+`setup` detects it and exits 2 naming the migration, which is one `git mv` the
+adopter can see. Manufacturing a state your own audit is written to complain
+about is worse than refusing to start.
+
+# Atomicity, stated honestly
+
+Each file is written to a temp path in its destination directory and renamed, so
+**no half-written file exists**. A nineteen-file sequence is not atomic as a
+*set*, and this does not pretend otherwise. The real safety is that `setup` is
+idempotent and re-runnable, which is what makes an interrupted run harmless.
+
+# Two mechanics worth keeping
+
+The `.gitignore` template is stored as `gitignore`, without the dot. As a real
+dotfile in the gem's own tree it would be a live gitignore governing its own
+directory — silently deciding what `git ls-files` reports, and therefore what
+ships.
+
+The generated file list is compared against `spec.files`, **not** against a glob
+of the template. Both sides of a glob-versus-glob comparison ignore
+`.gitignore`, so such a check passes in a checkout while the installed gem is
+short files — which is the failure it exists to catch.

data/.okf/scaffold/index.md

@@ -0,0 +1,8 @@
+# Scaffold
+
+What `okf pro setup` writes, and the decisions that shape it.
+
+* [ownership-not-subject](ownership-not-subject.md) - The gem-owned / seeded split, and why the obvious cut destroys the adopter's own files.
+* [no-date-ships](no-date-ships.md) - A shipped date ages into somebody else's calendar, and dormancy reads a fresh clone as an old bundle.
+* [collisions-and-refusals](collisions-and-refusals.md) - Never refuse wholesale, except into a flat-layout bundle.
+* [the-adopters-manual](the-adopters-manual.md) - The seeded README is the only file written for the owner; it sells the practice rather than the command set, and a fresh reader can measure whether it answers them.

data/.okf/scaffold/no-date-ships.md

@@ -0,0 +1,41 @@
+---
+type: Decision
+title: No date ships in the generated bundle
+description: A template is cloned an unknowable number of days after it is built, and every shipped date ages into somebody else's calendar.
+---
+
+# The rule
+
+No visible date anywhere in the generated tree: no log heading, no journal
+entry, no `updated` line on the board. The empty-state paths are the design —
+an undated `log.md` passes the audit, the session banner says `Last snapshot:
+none yet`, dormancy stays quiet while the journal is empty, and the first dirty
+day's stop gate hands over the computed snapshot line, which is the ritual
+teaching itself.
+
+# The failure that decided it
+
+Dormancy measures a bundle's age by its **oldest journal entry**. A shipped
+day-zero entry therefore makes a fresh clone read as an old bundle, and the
+adopter's first promotion draws a dormancy question it never earned — on their
+first day, from a gate they have no reason yet to trust.
+
+The journal guard compounds it: a past day is append-only, so a foreign entry is
+locked against correction forever.
+
+None of this is a rule about tidiness. It falls out of the same question
+[the ownership split](/scaffold/ownership-not-subject.md) answers: the bundle is
+the adopter's from the moment it is written, and a date in it is a claim about
+their days.
+
+# The exemption, which is required rather than cosmetic
+
+`projects/index.md` teaches the closure marker, and `Pairing::MARKER` **requires**
+a date. The example cannot lose its date without teaching a spelling the gate
+rejects, so dates inside code spans are exempt — and the exemption is what the
+invariant test encodes, rather than a blanket ban it would then have to violate.
+
+That coupling is pinned in both directions: every spelling the template and the
+skill teach must be one `MARKER` accepts, and every counter-example the skill
+names must be one it refuses. A spelling taught and rejected leaves the project
+open and tells the person who followed instructions that they did it wrong.

data/.okf/scaffold/ownership-not-subject.md

@@ -0,0 +1,63 @@
+---
+type: Decision
+title: The scaffold splits by ownership, not by subject
+description: Knowledge-versus-machinery is the obvious cut and the wrong one — it makes `upgrade` destroy exactly the hand-merge that adopting the gem asked for.
+---
+
+# The two classes
+
+**Gem-owned** — the hook wrapper, the pre-commit hook, the CI workflow, the
+skill. These carry [the contract](/contract/the-contract.md) and the exit-code
+protocol, so they must track the gem or a gate goes quietly wrong. `upgrade`
+rewrites them outright.
+
+**Seeded** — `README.md`, `CLAUDE.md`, `.gitignore`, `.claude/settings.json`,
+and the whole of `.okf/`. Written once, and the adopter's from that moment.
+
+# Why the obvious cut is wrong
+
+Sorting by subject matter — knowledge in one pile, machinery in the other — puts
+`CLAUDE.md`, `.gitignore` and `settings.json` on the machinery side, because
+that is what they look like. Then `upgrade` overwrites them.
+
+But `CLAUDE.md` at a repository root is the adopter's agent-instruction file;
+`.gitignore` accumulates project entries from day one; `settings.json` is where
+they add hooks of their own. Every one of them is a file the scaffold's own
+instructions tell them to merge into. An upgrade that rewrote them would destroy
+exactly the work adopting this thing asked for — and would do it on the run
+after the one where they did it.
+
+The question is not *what is this file about*. It is *whose file is it once it
+exists*.
+
+# The two front doors say the same thing twice, deliberately
+
+`README.md` and `CLAUDE.md` both describe the three doors, in nearly the same
+words. That is not drift waiting to be collapsed, and the argument for
+collapsing it is a real one that has to be answered rather than ignored: one
+operative copy beats two agreeing copies until the day they stop agreeing, and
+this bundle applies that rule everywhere else.
+
+It does not apply here, because these two files have **different readers and no
+shared moment**. `CLAUDE.md` is loaded by an agent at the start of every session
+that touches the bundle; `README.md` is read by a person, once, on the day they
+arrive. Neither reader sees the other's file, so a pointer from one to the other
+is a dead end rather than a single source: the agent will not follow a link to
+prose written for a human, and the human should not have to read the agent's
+instructions to learn how to arm a git hook.
+
+What the rule actually forbids is two copies of a *fact that changes* — a count,
+a path, a version. The doors are a fixed shape, and each file states them for
+its own reader in its own register. The seeded files are the adopter's from the
+moment they are written ([nothing rewrites them](/scaffold/no-date-ships.md)),
+so even a real divergence stays local to one repository rather than shipping.
+
+# The `.okf/` exemption
+
+Seeded files are staged beside the adopter's as `<path>.okf-pro-new` on a
+collision — except inside `.okf/`, where only missing files are added.
+
+A bundle that exists is a bundle already adopted, and eleven shadow files
+scattered through someone's knowledge is not a merge prompt, it is litter — in
+the one directory whose entire value is that everything in it was put there
+deliberately.

data/.okf/scaffold/the-adopters-manual.md

@@ -0,0 +1,114 @@
+---
+type: Learning
+title: The seeded README is the only document written for the owner
+description: Every other seeded file addresses the agent, so the adopter's README carries the exit, the limits and the price — and a fresh reader can measure whether it does.
+---
+
+# What the seeded README is for
+
+`setup` writes two prose files for humans and one for the machine. `CLAUDE.md`
+and `.claude/skills/okf-pro/` address the **agent**: the routing table, the
+frontmatter policy, the line grammars. `README.md` is the only thing in the tree
+addressed to the **person who owns the repository**, and it is the file they
+land on when they open the directory.
+
+That makes it a product surface rather than a courtesy, and it has to answer the
+questions the skill never will, because the agent has no use for them: what does
+a day cost me, what will this refuse, how do I change the numbers, and how do I
+turn it off.
+
+# The exit is the section that buys the rest
+
+A layer built out of refusals owes the reader a way to stop being refused, and
+the section documenting it is worth more than any section arguing the benefits.
+Stated as four escalating levers — one gate, all the agent-time gates, the
+commit door, everything — plus what survives removal, it converts "this thing
+constrains me" into "this thing constrains me *and told me where the door is*".
+
+Two properties make it real rather than reassuring:
+
+* **Every lever is verified by running it**, not described from the source. A
+  documented escape that does not work is worse than none — see
+  [a rule you can walk past](/design/a-rule-you-can-walk-past.md), whose fourth
+  clause is exactly this.
+* **What survives is stated.** Delete the machinery and `.okf/` is still a
+  bundle `okf validate` passes, because the format was never the enforcement's
+  to own. That is the payoff of building on a spec, and it is only worth
+  anything if the README says so out loud.
+
+The absence of an environment kill switch belongs here too, as a *feature* with
+its reason attached: a gate a stray `export` could disable is one nobody has
+reason to trust.
+
+# Measuring a README instead of proof-reading it
+
+A document's defects are not a matter of taste, and the maintainer is the worst
+available judge of their own page because they cannot un-know what it omits. The
+method that works: hand a reader **only that file**, ask a fixed set of a
+reader's real questions, and record which ones came back CONFIDENT, PARTIAL and
+BLANK.
+
+The blanks are the finding. Three surfaced here that no amount of re-reading had
+caught, in a file its author considered finished: no exit, no non-promises, and
+no picture of `board.md` — the one file the whole system pivots on, quoted only
+in fragments. A reader cannot report a section that was never there; they can
+report a question they could not answer, and those are the same fact.
+
+# The two rules the measurement produced
+
+**The same content can be right in one document and wrong in another, because of
+where the reader is standing.** The four-way gloss on the word *Pro* is good
+writing and belongs on the package page, where "is this a paid tier?" is a live
+misreading worth killing in the first screen. Dropped into the adopter's own
+repository it was the single sentence that lost the reader — someone standing in
+a new directory is asking what to do, not what the name means. Neither placement
+is a quality judgement about the prose. Position is the variable.
+
+**The loudest claim is the one that must carry evidence.** This page's method is
+claim-plus-evidence — the cap refusal, the snapshot line and the promote
+conflict are all shown as real output. The attestation gate was asserted as "the
+most valuable thing here" four separate times and shown exactly never, and it
+was the only claim a fresh reader singled out as unevidenced. A document that
+proves its cheap claims and asserts its expensive one has inverted its own
+argument: the reader calibrates on what you demonstrate, so the thing you most
+want believed is the thing that can least afford to be described.
+
+# The manual is for the practice, not the command set
+
+The first draft of this page was a CLI manual: every worked example a
+`$ okf pro …` transcript, a command table high on the page, and a "first hour"
+that was a list of verbs to type. It read as competent and it sold the wrong
+thing, because it described the machinery instead of the practice the machinery
+exists to hold.
+
+The system is agent-facilitated. The owner's actual moves are: *say what
+happened* to their agent, *triage* once a day, *approve or deny* an attestation,
+and *read the delta* at the next session start. The verbs are what the agent
+reaches for — the session banner tells it so in as many words — and the owner
+can go a week without typing one. A page whose every example is a shell prompt
+teaches the reader they are operating a tool, when what is being offered is a
+way of working.
+
+So the narrative shows board states and refusal messages, and the commands get
+one section, late, framed as what your agent uses and what you may occasionally
+want to run yourself. The gem's README can afford to lead with the command set —
+its reader is choosing a package — and the adopter's cannot.
+
+# The pitch is the practice, not the preservation
+
+The defensive framing — *your knowledge will rot and this stops it* — is true and
+undersells the thing. The offer is that being good at any craft has a shape:
+knowing what you are committed to, telling what you know from what you have
+merely read, not relearning a lesson twice, being able to say where a claim came
+from. Most people reach that shape after a decade, by accident, and many never
+do — because nothing in an ordinary week forces the question.
+
+The mechanism is structure rather than effort, and saying so matters: a small
+number of shapes, each with one place it lives and one form it takes, and gates
+that refuse the edits that break them. Give the practice a structure and the
+discipline stops being something you have to remember to have.
+
+That reading also settles a question a fresh reader raised twice: whether this is
+for software. None of the rules names code, so the answer is that the domain is
+irrelevant, and the page has to say it outright rather than let a week of
+tech-flavoured examples answer it by implication.

data/.okf/seam/bundler-scoping.md

@@ -0,0 +1,45 @@
+---
+type: Finding
+title: Bundler scoping switches the gates off, and the fix locks out the in-bundle adopter
+description: Gem discovery is bundle-scoped once bundler's variables are exported, so `okf pro` is an unknown command inside a bundle that does not name okf-pro.
+---
+
+# Both directions, both measured
+
+okf finds its extensions with `Gem.find_latest_files`, which is bundle-scoped
+once bundler's variables are in the environment.
+
+```
+BUNDLE_GEMFILE=okf/Gemfile bundle exec okf tui --help
+→ unknown command, exit 2
+```
+
+An agent working inside any bundled Ruby project would find every gate silently
+absent. But the repair has a mirror image: **inside a bundle,
+`Gem.find_latest_files("okf/plugin.rb")` returns `[]` outright**. A repository
+that deliberately vendors okf-pro through its own Gemfile is served *only* by
+the un-stripped run, so a wrapper that sanitised up front would lock it out of
+its own checker.
+
+The wrapper therefore tries un-stripped **first** and falls back to stripped,
+with `OKF_PRO_NO_UNBUNDLE=1` to pin the first. Both directions are drilled.
+
+Both branches live in [the wrapper](/seam/the-wrapper.md), which is the only
+place that can act before okf starts.
+
+# The variable list was wrong, and any list would be
+
+A first attempt stripped `BUNDLE_GEMFILE`, `BUNDLE_PATH` and `BUNDLE_BIN_PATH`.
+Bisected: `BUNDLE_PATH` and `BUNDLE_BIN_PATH` are inert, and the two that matter
+are `RUBYOPT` and `BUNDLER_SETUP`. `BUNDLER_SETUP` is recent enough that naming
+it is a bet on the adopter's bundler version — on a gem whose Ruby floor is 2.4.
+
+So the wrapper uses bundler's **own** restoration data, the `BUNDLER_ORIG_*`
+variables it exports for exactly this purpose, and is version-proof by
+construction rather than by an enumeration someone has to maintain.
+
+# The general shape
+
+When a dependency already records how to undo what it did, use that record. A
+hand-written inverse of somebody else's transformation is correct only for the
+versions you tested.

data/.okf/seam/identity-not-existence.md

@@ -0,0 +1,67 @@
+---
+type: Learning
+title: Existence is not identity
+description: A stray `okf` on PATH that exits 0 passes every gate, and no exit-code normalisation can tell it from a clean check.
+---
+
+# The claim that was wrong
+
+"Normalise the exit codes — map anything that is not 0 or 2 to 2 — and the stray
+binary is handled."
+
+It is not. A shim that exits **0** maps to 0. Every gate is off, silently, and
+the status carries no evidence either way: a clean check and a program that did
+nothing produce the same byte.
+
+# What replaced it
+
+`okf pro hook` writes `okf-pro-enforcer v1` to stderr as the first act of
+every check, and the wrapper refuses unless it sees that line. Costs one process
+and 0.16 s against 0.14 s for a bare normalised wrapper.
+
+The earlier design was a **handshake** — a second invocation, `okf pro
+contract`, answering the same string. It proved less at twice the cost: the
+handshake passed while the library was missing, because answering a question is
+not the same as reaching a check. The marker is emitted at the point where
+dispatch has already committed to running one, so its presence means the check
+was reached, not merely that the plugin loaded.
+
+# The door that had the argument written down and not applied
+
+The commit hook asked `command -v okf` and then trusted the exit status — the
+exact claim the section above calls wrong, at the one door that exists for the
+edit the agent hooks never see. A `#!/bin/sh\nexit 0` shim named `okf` made
+`okf pro records` and `okf pro audit` both pass, and the commit went through
+with nothing checked and nothing said.
+
+It proves identity the same way now, and it has to borrow the hook door to do
+it: the marker is written by `okf pro hook`, before a check runs, and the CI
+verbs do not emit it. So the handshake runs a real gate — `okf pro hook
+guard-verified` on an empty event, which reaches the check and gives it nothing
+to say — and requires the marker on stderr. Borrowing the door is the point:
+identity is proved by *reaching a check*, which is what the retired `okf pro
+contract` handshake could not do.
+
+The general form is worth stating, because this door had the reasoning
+available and did not apply it: **a defence written in one file is not a
+defence of the system.** Three doors exist precisely because each sees what the
+others cannot, so a proof that only one of them makes is a proof with a hole
+the shape of the other two.
+
+The check itself is [the wrapper's](/seam/the-wrapper.md), for the same reason
+everything else there is: it has to happen before the program being identified
+gets to answer for itself.
+
+# What it does not defend against
+
+A shim that deliberately prints the marker. That is a forgery, and no wrapper
+defends against one — the threat model here is a leaked variable, a stale shim,
+a half-installed gem. Claiming more would be the false confidence that is worse
+than no rule.
+
+# The general shape
+
+When a check's "pass" and a check's "absence" produce the same observable, no
+amount of interpreting that observable will separate them. A second, orthogonal
+observable has to exist — and it has to be emitted from the point that proves
+what you actually want proven.

data/.okf/seam/index.md

@@ -0,0 +1,8 @@
+# Seam
+
+The entry point, and the three ways it lets an unchecked edit through.
+
+* [three-fail-opens](three-fail-opens.md) - A ScriptError outside every rescue, a non-Integer status, and a SyntaxError nothing Ruby-side can reach.
+* [the-wrapper](the-wrapper.md) - Why the shell script cannot be collapsed into the checker, and why it stopped exec'ing.
+* [identity-not-existence](identity-not-existence.md) - A stray `okf` exiting 0 is indistinguishable from a clean gate by status alone.
+* [bundler-scoping](bundler-scoping.md) - Gem discovery is bundle-scoped, and the fix for that locks out the deliberate in-bundle adopter.

data/.okf/seam/the-wrapper.md

@@ -0,0 +1,42 @@
+---
+type: Decision
+title: Why the wrapper is a separate shell script
+description: A Ruby checker structurally cannot refuse on its own absence, so something already running has to — and it must not exec.
+---
+
+# The argument
+
+A script whose interpreter is missing exits 127. A script whose syntax the
+interpreter rejects exits 1. [Both are non-blocking](/contract/exit-codes.md).
+
+So a checker written in Ruby cannot refuse when it is missing, broken, or
+unparseable: by the time anything could report, nothing is running. That is the
+whole job of `.claude/hooks/run`, and it is why `settings.json` points there and
+never at `okf` directly.
+
+# It does not exec, and that is a change
+
+The prototype's wrapper ended in `exec`, and carried a comment saying a
+SyntaxError "no wrapper can catch, because nothing ran". That was true of an
+exec'ing wrapper and is false of this one: after `exec`, the wrapper is gone and
+the failing process's status is the answer. Staying resident is what lets it
+catch [the third fail-open](/seam/three-fail-opens.md).
+
+# Two things it must not do
+
+**It must not capture stdout.** A `PreToolUse` `ask` decision is JSON on stdout
+with exit 0, and the SessionStart banner travels the same way. A draft of this
+fix used `rc=$( okf pro hook "$check" )` to read the status — command
+substitution captures stdout, so `rc` became output-plus-status, the `case` fell
+through to its default, and the most load-bearing gate in the system stopped
+asking and started denying. The hardening broke the thing it was hardening.
+
+**It must not resolve `okf` twice.** The binary that proved itself is the binary
+that runs: `okf_bin="$(command -v okf)"` once, dispatched to absolutely. A
+re-resolution after changing the environment is a different program.
+
+# The residue
+
+`"$CLAUDE_PROJECT_DIR"` stays quoted in `settings.json`. Unquoted, a path with a
+space word-splits, the shell exits 127, and all four gates are disarmed by a
+directory name.

data/.okf/seam/three-fail-opens.md

@@ -0,0 +1,44 @@
+---
+type: Finding
+title: Three fail-opens in the plugin seam
+description: Moving the checker behind okf's plugin seam introduced three paths where a failure exits 1 — which the hook protocol reads as "proceed".
+---
+
+# The measurements
+
+`okf/exe/okf` is `exit OKF::CLI.start(ARGV)`, and `CLI#dispatch` calls
+`command.new(...).call(argv)` with **no rescue**. Discovery's own rescue wraps
+`require path` and catches `LoadError, StandardError`.
+
+1. **A `LoadError` from the deferred `require "okf/pro"` is a `ScriptError`**,
+   which is not a `StandardError` and is outside every rescue on the path.
+   Measured: process exit **1**, edit proceeds. This is what a half-installed or
+   partially-deleted gem looks like.
+2. **A non-Integer status** lands in the same place. `exit(true)` is 0 and
+   `exit(nil)` is 1; neither is a verdict, and a CLI ported from a standalone
+   binary plausibly calls `exit`.
+3. **A `SyntaxError` in `lib/okf/plugin.rb`** is a `ScriptError` too, so
+   discovery does not catch it either. The whole CLI dies with a parse dump and
+   exit 1, and **no gem code runs at all** — so neither Ruby-side guard can
+   reach it. Only [the wrapper](/seam/the-wrapper.md) can.
+
+# Where the guard has to live, and where it must not
+
+The rescue is in `OKF::CLI::Pro#call`, **outside** the require it guards. It
+cannot be inside `Pro::CLI.run`: that method is reached *through* the require
+that fails, so it would be a guard against the one thing it cannot witness.
+
+It is `rescue Exception`, which is the cop's textbook mistake everywhere else in
+this repo and the correct call exactly here — the failures are `ScriptError`s,
+and catching less than `Exception` is the same as catching nothing.
+
+`SystemExit` is re-raised rather than swallowed. `okf/pro.rb` refuses an
+under-floor Ruby with `exit 2`, and a rescue that turned that refusal into an
+error report would be the fail-open the whole method exists to close.
+
+# The general shape
+
+A deferred require is a load-time failure moved to call time. When the caller's
+error handling was written for the code being loaded rather than for the loading
+itself, the move creates a hole exactly the width of the exception hierarchy the
+caller does not catch.

data/.okf/testing/drills-over-units.md

@@ -0,0 +1,41 @@
+---
+type: Learning
+title: Drills, not unit tests, at the enforcement seam
+description: Every defect found in the entry point was a gate that passed while unable to check, which only a real process with a real exit status can catch.
+---
+
+# What a drill is here
+
+A subprocess, a real `PATH`, a real event on stdin, and the process's real exit
+status read back. Not a method call.
+
+That is not thoroughness for its own sake. The statements being tested are
+statements *about a process*: "the hook protocol reads this as non-blocking",
+"the shebang exits 127 when the interpreter is missing", "a bare locale makes
+`Encoding.default_external` US-ASCII and an em dash raises". None of them is
+observable from inside one interpreter with injected streams.
+
+# The list is the failure list
+
+Each drill names a way the seam was found to break, and every one of them is a
+gate that **passed**:
+
+| Drill | Before |
+|---|---|
+| okf-pro's library unloadable | exit 1, edit proceeds |
+| a syntax error in `plugin.rb` | exit 1, no gem code ran at all |
+| a stray `okf` exiting 0 | exit 0, every gate off |
+| `hook audit` | exit 0, "clean.", no stdin read |
+| a bundled environment | unknown command, exit 2, gates absent |
+| a project path with a space | exit 127, four gates disarmed |
+
+None of them is a wrong answer. They are all *no answer*, wearing the costume of
+a clean one — which is [the third clause](/contract/the-contract.md), from the
+outside.
+
+# And what must still get through
+
+Half the drills assert a **pass**: the event reaches the check, an `ask`
+decision reaches stdout intact, the session banner survives, the identity marker
+is stripped before anything downstream sees it. A wrapper that refused
+everything would satisfy every refusal drill in the table above.