git:20260820.3ce9341 to git:20260820.246ce59

+ Maintainer guide for okf-pro — `okf-pro` on RubyGems. It turns an

+ [Open Knowledge Format](https://github.com/serradura/okf-gem) bundle into a

+ working memory an agent is held to: `okf pro setup` writes the bundle and the

+ governance around it, and `okf pro hook` runs one gate against one hook event.

+ This file documents how to change the code without breaking its contracts.

+ This gem is a sibling in the okf-gem monorepo, one directory per gem under

+ `gems/`, beside the baseline `gems/okf/` it depends on.

+ [`../../AGENTS.md`](../../AGENTS.md) is the repo-level

+ guide and owns everything above a single gem — the layout, the shared testing

+ obligations, the PR shape, the release-title convention, the Git attribution

+ rule and the working style. What is here is okf-pro's own: the contract, the

+ exit codes, the seam, and the scaffold. Where the two overlap, the root is the

+ general rule and this is the instance.

+ ## Read the bundle first

+

+ **`.okf/` is this gem's structural documentation and its catalogue, and this

+ file no longer restates them.** What the code is, where each responsibility

+ lives, what every verb and check already answers, and how to add one all live

+ there — once, in the concept that owns them:

+

+ | you want | read |

+ | --- | --- |

+ | what a file under `lib/` does | [`.okf/structure/`](.okf/structure/) — one concept per layer, and it names every file |

+ | whether a capability already exists | [`.okf/capabilities/`](.okf/capabilities/) — sixteen verbs and nine checks, before you write a seventeenth |

+ | why a rule is a rule | [`.okf/design/`](.okf/design/) and [`.okf/contract/`](.okf/contract/) |

+ | how to add a verb or a check | [`.okf/testing/adding-a-verb.md`](.okf/testing/adding-a-verb.md) |

+ | what `setup` writes and who owns it | [`.okf/scaffold/`](.okf/scaffold/) |

+

+ `okf server .okf` from this directory reads it as a graph; `okf search @okf-pro

+ <term>` searches it from anywhere in the checkout.

+

+ The split used to run the other way: this file carried a hand-written Map of

+ `lib/**` and nothing checked it. `test/unit/bundle_catalog_test.rb` now fails

+ when a file under `lib/` is named by no concept, when a concept names a file

+ that is gone, or when either catalogue disagrees with `CLI::USAGE` and

+ `CLI::HOOK_NAMES` — so the structural layer is pinned where it lives, rather

+ than trusted where nobody looks.

+

+ Every defect this gem has ever had failed in the direction of silence. A gate

+ that cannot run, a check that was skipped, a shim on `PATH`, a status code the

+ protocol reads as "proceed" — each produces an unchecked bundle that is

+ indistinguishable from a clean one. When you change anything here, the question

+ to ask is not "is this correct?" but "what does it do when it cannot answer?"

+ The argument in full, and the failures behind each clause, is in

+ [`.okf/contract/`](.okf/contract/the-contract.md).

+ ## One door

+ This gem ships **no executable**. `lib/okf/plugin.rb` registers a `pro` command

+ with okf's registry, and `okf pro` is how a user gets here. That is load-bearing

+ rather than tidy, and more so than for the siblings that made the same call: the

+ scaffold's wrapper dispatches to **one** absolute `okf` and refuses unless that

+ binary identifies itself as the enforcer. A second entry point would be a second

+ thing for the wrapper to recognise, on the one code path where being wrong means

+ a gate waves an edit through. The seam is

+ [`.okf/structure/doors.md`](.okf/structure/doors.md).

+ Twelve rules. Where a concept carries the argument, this is the short form a

+ reviewer checks against and the link is the rest.

+ 1. **Ruby >= 2.4**, okf's own floor. It matters more here than anywhere else in

+ the repo: this code runs inside a git hook and a CI step on machines nobody

+ chose, and a checker that cannot parse is a checker that is off. The

+ forbidden-API list, broken out by the version that introduced each name, is

+ `@okf design/ruby-floor`; the ones this port had to undo were `filter_map`

+ (2.7) and endless ranges (2.6). The floor is checked twice — in the gemspec,

+ and at the top of `lib/okf/pro.rb`, which refuses with `exit 2` — and

+ `test/unit/pro_test.rb` pins that the two agree.

+ 2. **Runtime dependencies are exactly `okf`.** Everything else is stdlib. A gate

+ with a dependency tree is a gate that fails to install on the machine that

+ needed it most.

+ 3. **`hook`'s exit codes are the protocol's, not this repo's.** `0` passes, `2`

+ blocks, and **every other code — including `1` — is non-blocking**, so `hook`

+ never returns 1. Every other verb keeps the repo's 0/1/2 convention, and

+ `audit` reserves 1 for *findings* and spells "the checker broke" as 2.

+

+ Which is why **every verb in `CLI::READERS` routes through `parse_flags`**,

+ listed in `FLAGS` or not: absence from that table means "accepts none", and a

+ verb that skips the parser hands its undeclared flag to `BundleRoot.resolve`

+ as a directory and reports "holds no OKF bundle" — a pipeline's own typo,

+ spelled as a broken bundle. `test/integration/cli_test.rb` pins it over

+ `READERS`, which is the invariant and the whole of it.

+ 4. **The seam is where the contract's last Ruby line lives.** `plugin.rb` holds

+ a `rescue Exception` that re-raises `SystemExit`, with the cop disabled and

+ the reason beside it, and it must sit **outside** the `require "okf/pro"` it

+ guards. [`.okf/seam/three-fail-opens.md`](.okf/seam/three-fail-opens.md).

+ 5. **A `SyntaxError` in `plugin.rb` is unreachable from Ruby.** Discovery

+ rescues `LoadError, StandardError`; a `SyntaxError` is neither, and *no gem

+ code runs at all*. Only the scaffold's `.claude/hooks/run` can catch it,

+ which is why that wrapper no longer `exec`s. If you make it `exec` again, you

+ have reopened this.

+ 6. **`hook` whitelists its argument.** `Pro::CLI.run` dispatches the CI verbs

+ off the same first argv element a check name arrives in, so an adapter that

+ only stripped `hook` would make `okf pro hook audit` run a CI verb —

+ status 0, "clean.", reading no stdin and never blocking. The whitelist is

+ `Pro::CLI::HOOK_NAMES`, read from the library rather than copied.

+ 7. **The gate leaves no check silently unrun.** `Linter.call` with no options

+ skips `expired` and `stale` and still reports `healthy?`. Supply what a check

+ needs, or exclude it in source with its reason; never let

+ `stats[:skipped_checks]` come back non-empty and be discarded.

+ [`.okf/contract/silent-skips.md`](.okf/contract/silent-skips.md), pinned by

+ `test/integration/conformance_test.rb`.

+ 8. **A write verb is additive and targeted, never regenerative**, and that is

+ enforced rather than promised: each computes its new text purely, declares

+ the delta it intends, and `Conserve` refuses with exit 2 — nothing written —

+ if the actual delta differs in either direction. No verb writes a concept

+ body or sets `verified:`; a verb **refuses a missing file rather than writing

+ one**; and a name the caller supplies is contained twice over, because

+ `projects/<slug>` can be a symlink out.

+ [`.okf/design/derivation-that-writes.md`](.okf/design/derivation-that-writes.md)

+ and [`.okf/contract/containment-directions.md`](.okf/contract/containment-directions.md).

+ 9. **Friction is recorded at paths that already run, and never at a new hook

+ event** — `.claude/settings.json` is seeded, so a registration added there

+ would never reach an adopter through `upgrade`. The recorder refuses nothing

+ and blocks nothing, and still may not report a zero it did not count, nor ask

+ for a verb nothing is missing.

+ [`.okf/contract/telemetry-does-not-lie.md`](.okf/contract/telemetry-does-not-lie.md).

+ 10. **The scaffold splits by ownership, not by subject.** `upgrade` rewrites the

+ four gem-owned files and never touches a seeded one. Reclassifying

+ `CLAUDE.md`, `.gitignore` or `settings.json` as machinery makes `upgrade`

+ destroy exactly the hand-merge `setup` told the adopter to perform.

+ 11. **No date ships in the generated bundle**, outside a code span. The

+ exemption is required rather than cosmetic, and both directions of that

+ coupling are pinned by `test/unit/closure_grammar_test.rb`.

+ 12. **`lib/okf/pro/template/**` is what `setup` writes**, and it ships:

+ `test/integration/scaffold_test.rb` compares the generated list against

+ `spec.files`, *not* against a glob of the template, because a glob-versus-glob

+ comparison ignores `.gitignore` on both sides and would pass in a checkout

+ while the installed gem was short files. The `.gitignore` template is stored

+ as `gitignore`, without the dot, for the same class of reason.

+ ## Testing: drills first

+ The critical layer is `test/integration/wrapper_test.rb`, and it is unusual

+ enough to state plainly: **it runs the wrapper as a subprocess**, with a real

+ `PATH`, a real event on stdin, and the process's real exit status read back —

+ because the statements being tested are statements *about a process*, and none

+ of them is observable from inside one interpreter with injected streams. Every

+ drill there names a way the seam was found to break, and every one of them was a

+ gate that **passed**. The list, and why half the drills assert a *pass*, is

+ [`.okf/testing/drills-over-units.md`](.okf/testing/drills-over-units.md).

+ Beyond that the root guide's obligations apply unchanged, plus one file per verb

+ and subcommand and real fixtures rather than mocks. The step-by-step walk a new

+ verb or check owes is

+ [`.okf/testing/adding-a-verb.md`](.okf/testing/adding-a-verb.md).

+

+ ```

+ The Gemfile points `okf` at the checkout next door, so every run here — local,

+ CI, the floor container — resolves the checkout and nothing crosses to RubyGems

+ by default. Two things stand in that gap. `test/unit/gemspec_test.rb` is the

+ standing one: it fails the moment okf bumps and the declared floor does not

+ follow. And a run against the **published** kernel is the one that catches the

+ rest — this gem pins a frozen snapshot of okf's `Linter::SEVERITIES`, so a

+ released kernel that reclassified a check changes what the gate blocks on, which

+ is a difference no floor expresses:

+

+ ```sh

+ The 2.4 floor is proven the way the repo's is, from the root, stepping into this

+ gem:

+ `.okf/` ships inside the gem, and `rake okf` at the repo root validates and

+ lints it. It carries two things the code cannot say for itself. The first is the

+ argument — the three fail-opens in the seam, the check the gate skipped in

+ silence, why identity is not existence, what the ownership split in the scaffold

+ is protecting. The second is the structure and the catalogue, which used to live

+ in this file and now live where a test can hold them to the code.

+ Maintain it in the same commit as the code it documents. A new file under `lib/`

+ without a line in the concept that owns its layer is a red suite, not a stale

+ document — and so is a verb added to `USAGE` without its row in the catalogue.