okf-pro 1.0.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 89c3d1c35f2504c135c9875a57050aac3288610a5bb812b067faf1284905ab5b
-  data.tar.gz: 8d25d56ce3601cc0fd16e72b6ad43c358b69ee859baac16d0abcb855171cbc64
+  metadata.gz: a908d8394cc7ea78e25a744f080813d34eb656b77274e3bb8db4397d222c3950
+  data.tar.gz: 687919c65db7bf0d42bc48f475cd88f636c01aaf87f49443d92c6de0fd434fb9
 SHA512:
-  metadata.gz: 4f17f3f09f2aac6ceb618bcfb0e871c51cf55cc62b701b55b57154ff10b27c02fa84bdc09cc6b38759113f6536afd7246c74e2a3b4233c202c69b59df6a563b1
-  data.tar.gz: d9487c17f613c163b49283b6a626a3e74f0133eafcf1231bd9266d21237573d0d8f799fa4a637da6bda9379e2013d00454979d4be4acea908dd57555072fd774
+  metadata.gz: '0589ad1bd8edb04b767044692d20b271614fe37d60f598fe1b51ba436384142049da27d94d8281df54b0a485b658751e7ef2fe3d4c84a292b4593a61502d6c87'
+  data.tar.gz: 7afe1c08143bf0524f9deb5ce47e827276b59aa805f62cb65b2be5e5414bb542b1208a4b2a59826443ab1fde4e5680066fd047e6236007afc8b3e1b0e04e7ae3

data/.okf/capabilities/checks.md

@@ -0,0 +1,52 @@
+---
+type: Capability
+title: The checks — nine hook names, and the event each one rides
+description: What `okf pro hook <name>` accepts, which Claude Code event the scaffold wires it to, what it asks, and what it does when it cannot answer.
+generated:
+  by: human:maintainer
+  at: 2026-08-19
+---
+
+# The catalogue
+
+`OKF::Pro::CLI::HOOK_NAMES` is the source of truth, and it is strictly narrower
+than `NAMES`: the hook door accepts these nine and nothing else, because `run`
+dispatches the CI verbs off the same first argv element and a `settings.json`
+typo spelling `hook audit` would otherwise install a gate that reads no stdin,
+never blocks, and reports "clean." That failure is [gates-only-at-the-hook-door](/contract/gates-only-at-the-hook-door.md).
+
+| name | event | asks |
+|---|---|---|
+| `guard-verified` | `PreToolUse` on `Edit\|Write\|MultiEdit` | is this edit setting `verified:` on something the owner has not read? |
+| `journal-guard` | `PreToolUse` on `Edit\|Write\|MultiEdit` | is this rewriting a past journal day? |
+| `shell-guard` | `PreToolUse` on `Bash` | is this command about to write into the bundle behind the other two? |
+| `post-edit` | `PostToolUse` on `Edit\|Write\|MultiEdit` | the three below, in one process, sharing one bundle read |
+| `check-okf` | (composed into `post-edit`) | does the bundle still validate and lint? |
+| `cap-check` | (composed into `post-edit`) | is In flight over the cap? |
+| `reconcile-search` | (composed into `post-edit`) | what already says this? (**Law 1**) |
+| `stop-gate` | `Stop` | is the day's snapshot line written, and does it agree with the board? (**Law 2**) |
+| `session-context` | `SessionStart` | the banner: what is on the board, as the session opens |
+
+`check-okf`, `cap-check` and `reconcile-search` remain addressable on their own
+— they are in `CHECKS` and the door accepts them — but the scaffold wires
+`post-edit` instead, because the bundle read is the expensive part and three
+separate invocations paid for it three times over.
+
+# What they do when they cannot answer
+
+This is the half that matters, and it is the contract rather than a courtesy.
+
+`hook` reads **0 as pass and 2 as block, and every other code — including 1 —
+as non-blocking**: the tool call proceeds. So `hook` never returns 1. A gate
+that crashes therefore *passes*, from the protocol's side, which is why the
+reader scrubs rather than raises, why `CLI.run` refuses anything that still
+raises, and why the shell wrapper exists at all — a Ruby checker structurally
+cannot refuse on its own absence.
+
+A check that does not apply is not a failure: `Target.for` returns `nil` for an
+edit outside any bundle, and the gate passes. A check that could not run says
+so, in the same channel it would have used to refuse.
+
+The full table, and the argument, is [exit-codes](/contract/exit-codes.md); the
+three ways the seam let an unchecked edit through are
+[three-fail-opens](/seam/three-fail-opens.md).

data/.okf/capabilities/index.md

@@ -0,0 +1,12 @@
+# Capabilities
+
+What this gem can already answer. Read it before writing a check or a verb —
+the point of a catalogue is that the fifteenth thing is not the eighth thing
+under a new name.
+
+Both lists are pinned: `test/unit/bundle_catalog_test.rb` compares them against
+`OKF::Pro::CLI`'s own tables, so a verb added to the code and not to the
+catalogue is a red suite rather than a stale document.
+
+* [verbs](verbs.md) - The sixteen `okf pro` verbs: what each answers, which module implements it, and which flags it takes.
+* [checks](checks.md) - The nine hook names, the event each rides, and what it does when it cannot answer.

data/.okf/capabilities/verbs.md

@@ -0,0 +1,70 @@
+---
+type: Capability
+title: The verbs — what `okf pro` already answers
+description: Sixteen verbs in four families — scaffold, readers, writers, and the hook adapter — each with the module that implements it and the flags it declares.
+generated:
+  by: human:maintainer
+  at: 2026-08-19
+---
+
+# The catalogue
+
+`OKF::Pro::CLI::USAGE` is the source of truth for this table, and a test holds
+the two together.
+
+| verb | argument | answers | implemented in |
+|---|---|---|---|
+| `setup` | `[DIR]` | create or complete an agent's brain in DIR (default `.`) | `scaffold.rb` |
+| `upgrade` | `[DIR]` | rewrite the gem-owned governance files; stage the rest | `scaffold.rb` |
+| `skill` | `DEST` | (re)install okf-pro's agent skill on its own | `scaffold.rb` |
+| `state` | `[DIR]` | what is on the board, in one call — add `--full` for the corpus | `state.rb` |
+| `board` | `[DIR]` | one row per board line: section, dates, age, links | `board.rb` |
+| `audit` | `[DIR]` | every invariant at once — the CI door | `audit.rb` |
+| `records` | `[DIR]` | does the staged commit rewrite a past journal day? | `records.rb` |
+| `snapshot` | `[DIR]` | compute the day's counter line (prints, never writes) | `snapshot.rb` |
+| `unverified` | `[DIR]` | generated concepts still awaiting the owner's read | `attestation.rb` |
+| `friction` | `[DIR]` | what was done by hand that a verb could do | `friction.rb` |
+| `capture` | `TEXT` | append a dated Inbox line | `writes.rb` |
+| `promote` | `SEL` | Inbox or Backlog to In flight, refusing over the cap | `writes.rb` |
+| `demote` | `SEL` | In flight back to Backlog | `writes.rb` |
+| `journal` | `open` | create today's journal day and index it | `writes.rb` |
+| `close` | `SLUG` | the three mechanical closing moves for a project | `writes.rb` |
+| `hook` | `CHECK` | run one gate against a hook event on stdin | see [checks](checks.md) |
+
+# The four families, and why they differ
+
+**Scaffold** (`setup`, `upgrade`, `skill`) takes a *destination*, not a bundle.
+It does not go through `dir_argument`: `setup` into an empty directory is the
+whole point, and refusing one that holds no bundle would refuse every first run.
+
+**Readers** (`audit`, `records`, `snapshot`, `unverified`, `state`, `board`,
+`friction`) answer questions. Every one of them routes through `parse_flags`,
+listed in `FLAGS` or not — because absence from that table means "accepts none",
+and a verb that skips the parser hands its undeclared flag to `BundleRoot` as a
+directory and reports "holds no OKF bundle" as a *finding*: a pipeline's own
+typo, spelled as a broken bundle. `test/integration/cli_test.rb` pins it over
+`READERS`.
+
+**Writers** (`capture`, `promote`, `demote`, `journal`, `close`) are the shapes
+with exactly one correct form. Each is additive, targeted, and refused by
+`Conserve` rather than careful — see [the-writers](/structure/the-writers.md).
+They go through `writer_flags` instead, because their first argument is content
+and a flag there is data.
+
+**The hook adapter** is `hook`, and it is the odd one: its exit codes are the
+protocol's, not this repo's.
+
+# Flags
+
+Declared per verb in `CLI::FLAGS`, and the help text is read *from* that table
+rather than typed beside it:
+
+| verb | flags |
+|---|---|
+| `state` | `--json`, `--pretty`, `--full` |
+| `board` | `--json`, `--pretty`, `--section NAME` |
+| `snapshot` | `--json`, `--pretty` |
+| `unverified` | `--json`, `--pretty` |
+| `friction` | `--json`, `--pretty`, `--issue`, `--clear` |
+
+Everything else accepts none, and says so.

data/.okf/contract/containment-directions.md

@@ -2,6 +2,9 @@
 type: Decision
 title: Containment fails in four different directions, on purpose
 description: A path that escapes the bundle is refused, or ignored, or read as "not closed" — and which one is right is decided per call site by what a wrong answer costs, at the write door as well as the read one.
+generated:
+  by: human:maintainer
+  at: 2026-08-17
 ---
 
 # The rule

data/.okf/contract/exit-codes.md

@@ -2,6 +2,9 @@
 type: Decision
 title: Exit codes
 description: The hook protocol reads 0 and 2 and treats every other code as non-blocking, which inverts the repo's usual 0/1/2 convention for `hook` alone.
+generated:
+  by: human:maintainer
+  at: 2026-08-17
 ---
 
 # What the protocol actually reads
@@ -17,8 +20,8 @@ that lets the edit through.
 
 # The deviation, and where it stops
 
-`AGENTS.md` states the repo's convention as 0 ok / 1 failing bundle / 2 usage
-error. `okf pro hook` cannot keep it: 1 is a code the protocol ignores, so it
+The kernel's guide states the repo's convention as 0 ok / 1 failing bundle / 2
+usage error (`@okf capabilities/validator` carries it too). `okf pro hook` cannot keep it: 1 is a code the protocol ignores, so it
 is never returned. Every other verb keeps the convention.
 
 | Verb | 0 | 1 | 2 |

data/.okf/contract/gates-only-at-the-hook-door.md

@@ -2,6 +2,9 @@
 type: Decision
 title: Only gates answer at the hook door
 description: The CI verbs are not checks, and accepting one as a check name would report clean without ever reading the event.
+generated:
+  by: human:maintainer
+  at: 2026-08-17
 ---
 
 # The whitelist

data/.okf/contract/silent-skips.md

@@ -2,6 +2,9 @@
 type: Finding
 title: The checker broke its own third clause
 description: A default Linter.call skips two clock-gated checks and still reports healthy, so the gate reported clean over checks it never ran.
+generated:
+  by: human:maintainer
+  at: 2026-08-17
 ---
 
 # What was measured

data/.okf/contract/telemetry-does-not-lie.md

@@ -2,6 +2,9 @@
 type: Learning
 title: The third clause, applied to something that is not a check
 description: The friction recorder neither refuses nor blocks, and still may not report a zero it did not count — because a measurement that quietly degrades to "nothing happened" retires itself.
+generated:
+  by: human:maintainer
+  at: 2026-08-17
 ---
 
 # What it is

data/.okf/contract/the-contract.md

@@ -2,6 +2,9 @@
 type: Decision
 title: The contract
 description: Blocking checks fail closed, feedback checks fail loud, and no check ever fails silent — the three clauses every other decision in this gem is derived from.
+generated:
+  by: human:maintainer
+  at: 2026-08-17
 ---
 
 # The three clauses

data/.okf/design/a-comment-is-not-an-implementation.md

@@ -2,6 +2,9 @@
 type: Learning
 title: A comment is not an implementation
 description: A regex that claimed to anchor `>` to a redirection position never did, and the guard it powered fired on reads for its whole life — which is the shape of noise that retires a gate. The same class reaches comments, docstrings and the bundle's own concepts.
+generated:
+  by: human:maintainer
+  at: 2026-08-17
 ---
 
 # What happened

data/.okf/design/a-rule-you-can-walk-past.md

@@ -2,6 +2,9 @@
 type: Learning
 title: A rule you can walk past is a preference
 description: Why the gates block rather than warn, why three doors are not redundant, and why the day's ritual must stay silent on a day nobody worked.
+generated:
+  by: human:maintainer
+  at: 2026-08-17
 ---
 
 # The claim

data/.okf/design/derivation-that-writes.md

@@ -2,6 +2,9 @@
 type: Decision
 title: Derivation may write, under a conservation guard
 description: Failure mode 07 forbids an LLM regenerating a view; it does not forbid a Ruby function performing a declared, line-conserving edit — and the status quo it was written against was the failure mode itself.
+generated:
+  by: human:maintainer
+  at: 2026-08-17
 ---
 
 # The verdict, read precisely

data/.okf/design/failure-modes.md

@@ -2,6 +2,9 @@
 type: Finding
 title: The eight failure modes
 description: The named ways a personal knowledge system dies — three by lying and five by telling the truth badly — and the mechanism that answers each.
+generated:
+  by: human:maintainer
+  at: 2026-08-17
 ---
 
 # The catalogue

data/.okf/design/lineage.md

@@ -11,6 +11,9 @@ sources:
     resource: https://gettingthingsdone.com/
     title: Getting Things Done
     author: David Allen
+generated:
+  by: human:maintainer
+  at: 2026-08-17
 ---
 
 # Nothing here is invented from nothing

data/.okf/design/structure-laws.md

@@ -2,6 +2,9 @@
 type: Decision
 title: Structure laws
 description: The seven rules that decide whether a room, a field or a file may exist — a directory is a retrieval question, and state lives in exactly one place.
+generated:
+  by: human:maintainer
+  at: 2026-08-17
 ---
 
 # The rules

data/.okf/design/the-residue.md

@@ -2,6 +2,9 @@
 type: Learning
 title: The residue
 description: Trust measures process, never truth — a misheard number, sourced and verified, reaches maximum trust while being false, and no law closes it.
+generated:
+  by: human:maintainer
+  at: 2026-08-17
 ---
 
 # The limit

data/.okf/design/three-laws.md

@@ -2,6 +2,9 @@
 type: Decision
 title: Three laws
 description: Nothing is written without confronting what is already there; every view confesses its blind spots; attention is a budget, renegotiable but never silently exceeded.
+generated:
+  by: human:maintainer
+  at: 2026-08-17
 ---
 
 # The laws

data/.okf/design/three-pillars.md

@@ -2,6 +2,9 @@
 type: Overview
 title: Three pillars
 description: Know, Work and State — three questions no one of them can answer alone, and why the zones of the bundle are the pillars themselves.
+generated:
+  by: human:maintainer
+  at: 2026-08-17
 ---
 
 # The three questions

data/.okf/index.md

@@ -4,25 +4,34 @@ okf_version: "0.2"
 
 # okf-pro knowledge bundle
 
-The non-obvious knowledge behind **okf-pro** — the gem that turns an
-[okf](@okf) bundle into a working memory an agent is held to. The `README`
-documents the verbs and the scaffold, and `AGENTS.md` carries the contracts a
-change has to keep; this bundle deliberately restates neither.
+The knowledge behind **okf-pro** — the gem that turns an okf bundle (`@okf`)
+into a working memory an agent is held to. It is written to be read *before*
+opening `lib/`, so an agent about to add a check, a verb or a test does not
+re-derive the layering and does not rebuild something this gem already answers.
 
-It captures two things. The first is the argument the gem serves — three laws,
-the failures each one closes, and the limit each one admits — because the rules
-are borrowed and reasoned rather than obvious, and a rule whose reasoning is
-lost gets re-argued from scratch every time someone questions it.
+`AGENTS.md` beside it carries the contract, the constraints and the commands,
+and routes here for everything else; the `README` is the adopter's. What used
+to be a hand-maintained Map of `lib/**` in `AGENTS.md` now lives in
+[Structure](structure/), pinned by `test/unit/bundle_catalog_test.rb` — the
+code is the truth and this bundle is the claim, so the two cannot drift
+quietly.
 
-The second is the thing this gem is unusual for: **every defect here fails
-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 of them
-produces an unchecked bundle that is indistinguishable, from the outside, from a
-clean one. So the knowledge worth recording is not what the checks assert; it is
-where the machinery around them can stop asserting anything without saying so.
+It also captures the argument the gem serves — three laws, the failures each
+one closes, and the limit each one admits — because the rules are borrowed and
+reasoned rather than obvious, and a rule whose reasoning is lost gets re-argued
+from scratch every time someone questions it.
+
+And the thing this gem is unusual for: **every defect here fails 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 of them produces
+an unchecked bundle that is indistinguishable, from the outside, from a clean
+one. So the knowledge worth recording is not what the checks assert; it is where
+the machinery around them can stop asserting anything without saying so.
 
 # Areas
 
+* [Structure](structure/) - Every file under `lib/`, grouped by the layer that owns it: the doors, the readers, the gates, the guards, the writers, the scaffold, the recorder.
+* [Capabilities](capabilities/) - The catalogue: sixteen verbs and nine checks — what each answers, before you write a seventeenth.
 * [Design](design/) - Why the rules exist: three pillars, three laws, the eight failures they close, and what was borrowed.
 * [Contract](contract/) - Fail closed, fail loud, never fail silent — and the exit codes that make it true.
 * [Seam](seam/) - The plugin entry point, the three ways it fails open, and the wrapper that closes them.

data/.okf/log.md

@@ -1,5 +1,25 @@
 # Update Log
 
+## 2026-08-19
+
+* **Every concept declares `generated:`.** The dates are read from git with
+  `--follow`, so a rename is not mistaken for authorship — the first attempt
+  stamped all 37 with the day the files *moved*, which is provenance invented
+  rather than recorded, and was thrown away.
+
+* **The structure and the catalogue moved into this bundle, and a test holds
+  them to the code.** `AGENTS.md` carried a hand-maintained Map of `lib/**` that
+  nothing checked, so a file could arrive, move or leave and the Map would keep
+  reading plausibly. [Structure](/structure/) now owns it — one concept per
+  layer, naming every file — and [Capabilities](/capabilities/) owns the
+  catalogue of what the sixteen verbs and nine checks already answer, which is
+  the list an agent has to read before writing a seventeenth.
+  `test/unit/bundle_catalog_test.rb` is the pin, and it bites in both
+  directions: a file no concept names, a concept naming a file that is gone, or
+  a catalogue that disagrees with `CLI::USAGE` or `CLI::HOOK_NAMES`.
+  [testing/adding-a-verb](/testing/adding-a-verb.md) is the walk a new surface
+  owes, ending at the catalogue entry the pin will demand.
+
 ## 2026-08-17
 
 * **okf-pro 1.0.0.** The prototype checker — carried inside a template

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

@@ -2,6 +2,9 @@
 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.
+generated:
+  by: human:maintainer
+  at: 2026-08-17
 ---
 
 # Never refuse wholesale

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

@@ -2,6 +2,9 @@
 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.
+generated:
+  by: human:maintainer
+  at: 2026-08-17
 ---
 
 # The rule

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

@@ -2,6 +2,9 @@
 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.
+generated:
+  by: human:maintainer
+  at: 2026-08-17
 ---
 
 # The two classes

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

@@ -2,6 +2,9 @@
 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.
+generated:
+  by: human:maintainer
+  at: 2026-08-17
 ---
 
 # What the seeded README is for

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

@@ -2,6 +2,9 @@
 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.
+generated:
+  by: human:maintainer
+  at: 2026-08-17
 ---
 
 # Both directions, both measured
@@ -10,7 +13,7 @@ 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
+BUNDLE_GEMFILE=gems/okf/Gemfile bundle exec okf tui --help
 → unknown command, exit 2
 ```
 

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

@@ -2,6 +2,9 @@
 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.
+generated:
+  by: human:maintainer
+  at: 2026-08-17
 ---
 
 # The claim that was wrong

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

@@ -2,6 +2,9 @@
 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.
+generated:
+  by: human:maintainer
+  at: 2026-08-17
 ---
 
 # The argument

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

@@ -2,6 +2,9 @@
 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".
+generated:
+  by: human:maintainer
+  at: 2026-08-17
 ---
 
 # The measurements

data/.okf/structure/doors.md

@@ -0,0 +1,80 @@
+---
+type: Component
+title: The doors, and the constants the contract is written in
+description: Three entry points — the plugin verb, the hook adapter, the CI verbs — all through one dispatcher, and the exit codes every one of them answers in.
+generated:
+  by: human:maintainer
+  at: 2026-08-19
+---
+
+# The files
+
+| file | what it owns |
+|---|---|
+| `lib/okf/pro.rb` | the contract's constants, the two reads, `NO_RECONCILE`, and the require list that loads everything |
+| `lib/okf/plugin.rb` | `OKF::CLI::Pro` — the okf extension seam, and the last Ruby-side line of the contract |
+| `lib/okf/pro/cli.rb` | `OKF::Pro::CLI` — dispatch, the verb tables, the flag parser, and the identity marker |
+| `lib/okf/pro/version.rb` | `OKF::Pro::VERSION` |
+
+# `pro.rb` is the vocabulary, not a namespace
+
+Three constants, and every exit this gem takes is one of them:
+
+* `PASS = 0`, `BLOCK = 2` — the only two codes the hook protocol reads as
+  meaning anything.
+* `FAIL = 1` — `audit` only. It is *findings*, which is CI's vocabulary and not
+  the hook's; the hook door never returns it, because the protocol reads it as
+  proceed.
+
+Then three things every layer above uses. `read_text` is the raw read, as
+bytes, forced to UTF-8 and scrubbed — it failed open twice before it looked
+like this, once on an unset `LANG` making `Encoding.default_external` US-ASCII
+and once on a single invalid byte raising out of `match?`. `read_contained` is
+the same read through the kernel's `SafeRead.read!`, for the callers that
+already hold a root and must refuse a symlink leaving it. `newline_terminated`
+guarantees the final newline a splice depends on.
+
+`require "okf/pro"` loads **everything**, deliberately: this gem is not an
+embedding library, it is a checker, and every module is on the path of some
+gate. It also refuses at the top — a `LoadError` on `okf` prints
+`ENFORCEMENT DEGRADED` and exits 2, rather than letting the edit through.
+
+# `plugin.rb` is where the contract runs out of Ruby
+
+It registers `pro` with the kernel's command registry, and holds a
+`rescue Exception` that re-raises `SystemExit`, cop disabled, reason beside it.
+The failures it catches are `ScriptError`s, which are not `StandardError`s, and
+it must sit **outside** the `require "okf/pro"` it guards — inside the CLI it
+could not catch the `LoadError` of the require that reaches it.
+
+That is the first of [three fail-opens](/seam/three-fail-opens.md) this seam had.
+
+A `SyntaxError` here is unreachable from Ruby altogether: discovery rescues
+`LoadError, StandardError`, a `SyntaxError` is neither, and no gem code runs at
+all. Only the scaffold's shell wrapper can catch that, which is why the wrapper
+no longer `exec`s.
+
+# `cli.rb` is one dispatcher and four tables
+
+The verb tables are the catalogue, and they are read rather than copied
+wherever a second copy would drift:
+
+| table | what it holds |
+|---|---|
+| `CHECKS` | the eight hook checks, name to lambda |
+| `HOOK_NAMES` | `CHECKS.keys` plus `session-context` — the **only** names the hook door accepts |
+| `READERS` | the seven question-answering verbs |
+| `WRITERS` | the five verbs that change a file |
+| `SCAFFOLD` | `setup`, `upgrade`, `skill` — they take a destination, not a bundle |
+| `USAGE` | the printed command list, joined to `help_rows` by a test rather than by a second literal |
+| `FLAGS` | what each verb accepts, declared; absence means "accepts none" |
+
+`HOOK_NAMES` exists because `run` dispatches the CI verbs off the same first
+argv element a check name arrives in. Without the whitelist a `settings.json`
+typo spelling `hook audit` installs a gate that reads no stdin, cannot block,
+and reports "clean."
+
+`MARKER` — `okf-pro-enforcer v1` on stderr immediately before a check runs — is
+the whole of the wrapper's identity proof, and it is emitted *here* rather than
+at the door so that its presence means the check was reached, not merely that
+the plugin loaded.

data/.okf/structure/index.md

@@ -0,0 +1,18 @@
+# Structure
+
+Every file under `lib/`, grouped by the layer that owns it. One concept owns
+each file, and `test/unit/bundle_catalog_test.rb` fails if that stops being true
+in either direction — a file no concept names, or a concept naming a file that
+is gone.
+
+Read it as a pipeline. An event arrives at a door, the world is read into data,
+a gate or a guard asks one question of that data, and — only for the write
+verbs — a transform is planned, conserved and committed.
+
+* [doors](doors.md) - `lib/okf/pro.rb`, `lib/okf/plugin.rb`, `lib/okf/pro/cli.rb`, `lib/okf/pro/version.rb` — the seam, the contract's constants, and the one dispatcher.
+* [reading-the-world](reading-the-world.md) - `bundle_root.rb`, `event.rb`, `target.rb`, `board.rb`, `log.rb`, `records.rb` — where the bundle is, what arrived, and the two documents as data.
+* [the-gates](the-gates.md) - `reconcile.rb`, `budget.rb`, `closing.rb`, `snapshot.rb`, `attestation.rb`, `pairing.rb`, `conformance.rb`, `state.rb`, `audit.rb` — one question each, and the two doors that ask them all.
+* [the-guards](the-guards.md) - `guards.rb`, `shell_guard.rb` — the trust rules, and the same rules at the door a shell command comes through.
+* [the-writers](the-writers.md) - `conserve.rb`, `board/edit.rb`, `log/edit.rb`, `writes.rb` — pure transforms, a declared delta, and the refusal that enforces it.
+* [the-scaffold](the-scaffold.md) - `scaffold.rb` and the template tree it writes.
+* [the-recorder](the-recorder.md) - `friction.rb` — telemetry about the tooling, which refuses nothing and blocks nothing.

data/.okf/structure/reading-the-world.md

@@ -0,0 +1,65 @@
+---
+type: Component
+title: Reading the world — the root, the event, and the two documents as data
+description: Six files that answer where the bundle is, what arrived on stdin, and what `board.md` and `log.md` say — before any gate has an opinion.
+generated:
+  by: human:maintainer
+  at: 2026-08-19
+---
+
+# The files
+
+| file | pure? | what it owns |
+|---|---|---|
+| `lib/okf/pro/bundle_root.rb` | pure | where the bundle is, given where the agent is |
+| `lib/okf/pro/event.rb` | pure | the hook event — the only place untrusted input is parsed |
+| `lib/okf/pro/target.rb` | shell | bundle root + edited path, or `nil` when a check cannot apply |
+| `lib/okf/pro/board.rb` | pure | `board.md` as data: sections, budget header, links, dates |
+| `lib/okf/pro/log.rb` | pure | `log.md` as data: the snapshot line, the newest day |
+| `lib/okf/pro/records.rb` | shell | the append-only record, asked of git at the commit door |
+
+# Where the root is
+
+`BundleRoot.resolve` walks from a starting directory to the bundle it belongs
+to. `DIR` is `.okf`, and `root_kind` distinguishes the repository root from a
+level root from a plain directory, because "the bundle" is a different question
+in a monorepo than in a repository holding one. It is the one reader that does
+**not** go through `read_contained`: it is deciding where the root *is*, so it
+has none to contain against — a raise there would be a permanent lockout and a
+rescue would mis-root the bundle and disarm the journal guard.
+
+# What arrived
+
+`Event` is a class rather than a module, and it is the only place untrusted
+input is parsed. It answers `tool_name`, `tool_input`, `file_path`, `command`,
+`cwd`, `added_text`, `stop_hook_active?` — and `parse_error?`, which is the
+honest answer to malformed JSON rather than an exception thrown at a gate that
+would then not run.
+
+`Target.for(event)` turns an event into a root plus a relative path, or `nil`
+when the check simply does not apply — an edit outside any bundle is not a
+failure, and a gate that treated it as one would refuse every edit in the
+repository. `Target#read` and `#exist?` are how a gate reaches a file inside
+its own root.
+
+# The two documents
+
+`Board` and `Log` are the parsers, and they are pure — no disk, no stdio.
+
+`Board` strips HTML comments first (`strip_comments`, then `visible`), because
+a commented-out row is not on the board and every count downstream depends on
+that being true. It answers `rows`, `count`, `budget`, `targets`, `line_date`,
+`chase_date`, and the three grammar checks — `missing_sections`,
+`date_findings`, `stray_bullets` — against the six `SECTIONS` it knows.
+
+`Log` answers the questions the closing gate asks of `log.md`:
+`snapshot_under?` for a given day, `days`, `newest_day`, `latest_snapshot_entry`,
+and `malformed_days`. `DAY_HEADING` and the deliberately looser `DAYISH_HEADING`
+exist as a pair — the second is how a heading that *looks* like a day but is not
+one gets reported instead of silently skipped.
+
+The gates that consume all six are [the-gates](/structure/the-gates.md).
+
+`Records` is the git question: `staged_violations` asks the index, not the
+working tree, whether a commit rewrites or deletes a past journal day. It is at
+the commit door because that is the only door where the staged tree is the truth.

data/.okf/structure/the-gates.md

@@ -0,0 +1,64 @@
+---
+type: Component
+title: The gates — one question each, and the two doors that ask them all
+description: Nine files, each answering one invariant, plus `audit` (the CI door) and `state` (the readers' payload) which ask the same questions from a different side.
+generated:
+  by: human:maintainer
+  at: 2026-08-19
+---
+
+# The files
+
+| file | the law or the question |
+|---|---|
+| `lib/okf/pro/reconcile.rb` | **Law 1** — what already says this, while the write is still hot |
+| `lib/okf/pro/budget.rb` | **Law 3** — the cap, and the dormancy question |
+| `lib/okf/pro/closing.rb` | **Law 2** — the stop gate, and the session banner |
+| `lib/okf/pro/snapshot.rb` | Law 2's counters, derived — a checker, never a generator |
+| `lib/okf/pro/attestation.rb` | what still awaits the owner's read |
+| `lib/okf/pro/pairing.rb` | the board↔work invariants, both directions |
+| `lib/okf/pro/conformance.rb` | `okf validate` + `okf lint`, in process |
+| `lib/okf/pro/audit.rb` | the CI door: the same invariants minus the tool event |
+| `lib/okf/pro/state.rb` | the readers' payload — cheap by contract |
+
+The laws themselves are [design/three-laws](/design/three-laws.md); this concept
+is where each one is implemented.
+
+# Snapshot is a checker, not a generator
+
+`Snapshot.counters` recomputes every number from the board and the bundle;
+`Snapshot.line` renders it; `Snapshot.parse` reads a line already written; and
+`Snapshot.verify` compares the two and reports the difference. There is no
+`--write`, and there deliberately never will be: a writer and a checker sharing
+a code path agree trivially, which is exactly what Law 2's confession must not
+be able to do.
+
+# Conformance is the kernel's answer, not a second one
+
+`Conformance.check` runs the kernel's validator and linter in process against
+the target's bundle. Every conformance and curation question is okf's to answer
+— this gem owns the policy on top. The one rule it adds is the contract's third
+clause: `Linter.call` with no options skips `expired` and `stale` and still
+reports `healthy?`, so `confession` surfaces what was not run rather than
+reporting clean over a silent skip.
+
+# Two doors, one set of invariants
+
+`Audit.call` is the CI door. It asks `structure`, `conformance`, `curation`,
+`snapshot` and `pairing` of a tree with no tool event in sight, and it reserves
+exit 1 for *findings* — spelling "the checker broke" as 2, because a pipeline
+that cannot tell those apart learns to ignore both. `ambiguous_layout` is its
+refusal when it cannot tell which bundle it was pointed at.
+
+`State.call` is the other side: what is on the board, in one call, cheap by
+contract. `full: true` is the one parse it will pay for — the readers exist
+because an agent working in a seeded bundle rediscovered the board by reading
+raw markdown while the stop gate was already computing it.
+
+# Pairing holds the one git shell-out
+
+`Pairing.failures` asks both directions at once: a project with no board line,
+a board line with no project, a target that does not resolve, a link to a
+closed project, a read line gone stale. `MARKER` and `NEGATED` are a pair — the
+second is why "never closed" is not read as a closure marker. `dirty_markdown?`
+is the git shell-out, and it is the only one outside `records.rb`.

data/.okf/structure/the-guards.md

@@ -0,0 +1,43 @@
+---
+type: Component
+title: The guards — the trust rules, and the same rules at the shell door
+description: Two files asking the same questions at two doors, because a `cat > concept.md` is seen by neither the Edit tool nor the file-path checks.
+generated:
+  by: human:maintainer
+  at: 2026-08-19
+---
+
+# The files
+
+| file | the door |
+|---|---|
+| `lib/okf/pro/guards.rb` | an `Edit` or `Write` tool event: the trust rules on the text about to land |
+| `lib/okf/pro/shell_guard.rb` | a `Bash` tool event: the same rules, read out of a command line |
+
+# What they ask
+
+`Guards.attests?` is the trust question — does this text set `verified:`?
+`ATTESTATION` matches the block form, `FLOW_ATTESTATION` the inline-mapping
+form, and both exist because a rule that only knew one spelling waved the other
+through. `guard_verified` is the gate that uses them; `journal_guard` is the
+append-only rule for `journal/YYYY-MM-DD.md`, which `JOURNAL_ENTRY` recognises.
+
+`ShellGuard.check` reads the same rules out of a command. `MUTATORS` is the
+list of commands that can write, `SEPARATORS` splits a compound command so a
+mutator after `&&` is not missed, `MARKDOWN` finds the paths, and `own_write?`
+is what keeps `okf pro` verbs from being refused by the guard that exists to
+make people use them.
+
+# Why there are two
+
+A gate reads a tool event. A shell redirect is not one — a `cat > board.md`
+carries no `file_path`, so `guard_verified` never sees it and `Target.for`
+returns nothing to check. Without the shell door the whole trust layer is one
+`bash -c` away from being off, which is the shape every defect in this gem has
+had: not a wrong answer, a *no* answer wearing the costume of a clean one.
+
+The write verbs the guards are protecting are [the-writers](/structure/the-writers.md).
+
+That is also why the write verbs refuse text spanning lines rather than
+escaping it — a verb invoked through Bash is seen by neither guard, so the
+safety there is by construction rather than by inspection.

data/.okf/structure/the-recorder.md

@@ -0,0 +1,49 @@
+---
+type: Component
+title: The recorder — telemetry that refuses nothing and still may not lie
+description: "`friction` counts what was done by hand that a verb could have done, at paths that already run; it blocks nothing, and it may not report a zero it did not count."
+generated:
+  by: human:maintainer
+  at: 2026-08-19
+---
+
+# The file
+
+| file | what it owns |
+|---|---|
+| `lib/okf/pro/friction.rb` | the friction log: record, report, classify, clear |
+
+# What it is, and what it is not
+
+It is telemetry about the *tooling*, not about the knowledge base. It refuses
+nothing and blocks nothing, and it is **not** one of `okf pro state`'s sources —
+mixing it in would make a reader's payload depend on how the last session was
+typed.
+
+Nor does it register a new hook event. `.claude/settings.json` is a seeded file,
+so a registration added there would never reach an existing adopter through
+`upgrade`. The recorder rides the paths that already run.
+
+# It still answers to the third clause
+
+A recorder that fails quietly reports a clean session it never observed, which
+is the contract's third clause broken by something that is not even a check.
+So:
+
+* a failed write leaves `MARKER` (`okf-pro-friction.unavailable`) behind, and
+  `available?` is asked directly rather than inferred from an empty log;
+* an unwritable `.tmp/` is confessed, not shrugged at;
+* an unparseable line is reported rather than skipped.
+
+The argument is [telemetry-does-not-lie](/contract/telemetry-does-not-lie.md).
+
+# And it may not ask for a verb that is not missing
+
+`own_command?` recognises this gem's own invocations — including through
+`WRAPPERS` (`bundle exec`, `env`, `sudo` and the rest) — so `okf pro capture`
+is not recorded as friction against `okf pro capture`. `covered_by` and
+`verb_covered?` decide whether a row names something a verb would actually
+answer: a shell redirect's honest answer is `SHELL_ANSWER` — Edit or Write,
+because the trust guards read a tool event and a redirect is none. The session
+banner counts only the rows a verb would answer, and `--issue` prints nothing
+when nothing was recorded.

data/.okf/structure/the-scaffold.md

@@ -0,0 +1,42 @@
+---
+type: Component
+title: The scaffold — what `setup` writes, and who owns it afterwards
+description: "One generator, two template trees, and a split by ownership rather than by subject: `upgrade` rewrites the gem's files and never touches a seeded one."
+generated:
+  by: human:maintainer
+  at: 2026-08-19
+---
+
+# The file
+
+| file | what it owns |
+|---|---|
+| `lib/okf/pro/scaffold.rb` | `setup`, `upgrade`, `skill` — the generator and its refusals |
+
+Plus `lib/okf/pro/template/`, which is not code: it is the tree `setup` writes.
+It ships, and the gemspec says why — a gem without it installs a verb that
+cannot do its job.
+
+# Two trees, and the split is ownership
+
+`GEM_DIR` (`template/gem/`) holds the machinery: `upgrade` rewrites those files
+in place, every time, without asking. `SEED_DIR` (`template/seed/`) holds the
+adopter's: written once by `setup`, never touched again.
+
+Reclassifying `CLAUDE.md`, `.gitignore` or `settings.json` as machinery would
+make `upgrade` destroy exactly the hand-merge `setup` told the adopter to
+perform. The argument is [ownership-not-subject](/scaffold/ownership-not-subject.md).
+
+`DOTFILES` maps `gitignore` to `.gitignore` — stored without the dot, because a
+dotfile inside the template is a file `git ls-files` and every glob treat
+differently. `EXECUTABLE` is the two files that must land with the bit set.
+`SUFFIX` (`.okf-pro-new`) is what a collision is written as instead of an
+overwrite; `flat_layout_refusal` is what happens when the destination is not a
+shape this gem can complete.
+
+# What must not appear
+
+No date ships in the generated bundle, outside a code span — and the exemption
+*is* required rather than cosmetic, because the closure marker has to be taught
+and `Pairing::MARKER` requires a date. Both directions of that coupling are
+pinned by `test/unit/closure_grammar_test.rb`. See [no-date-ships](/scaffold/no-date-ships.md).

data/.okf/structure/the-writers.md

@@ -0,0 +1,60 @@
+---
+type: Component
+title: The writers — pure transforms, a declared delta, and the refusal that enforces it
+description: Every write verb computes its new text without touching the disk, declares the lines it means to add, remove and move, and is refused if the actual delta differs.
+generated:
+  by: human:maintainer
+  at: 2026-08-19
+---
+
+# The files
+
+| file | pure? | what it owns |
+|---|---|---|
+| `lib/okf/pro/conserve.rb` | pure | the write contract, enforced: line multisets in, refusals out |
+| `lib/okf/pro/board/edit.rb` | pure | the board's text transforms, and the keyed selectors |
+| `lib/okf/pro/log/edit.rb` | pure | a dated line, under its day, newest-first |
+| `lib/okf/pro/writes.rb` | shell | the mechanical writers: read, transform, guard, rename |
+
+# The shape every verb has
+
+Read the file. Compute the new text with a **pure** transform — `Board::Edit` and
+`Log::Edit` cannot touch the disk, which is what makes the transform testable
+without a fixture and unable to half-write. Declare the delta: which lines were
+added, removed, moved. Then `Conserve.check` compares the declared delta against
+the actual one and refuses with exit 2 — **nothing written** — if they differ in
+either direction.
+
+That is the enforcement of [derivation-that-writes](/design/derivation-that-writes.md):
+a write verb is additive and targeted, never regenerative. `Conserve.normalize`
+chomps, so a missing final newline is not a delta; `counts` and `subtract` do the
+multiset arithmetic, so a line moved between sections is a move rather than a
+delete plus an add.
+
+# What the verbs are
+
+`Writes` holds `capture`, `promote`, `demote`, `journal_open` and `close`, and
+each one is a plan-then-commit pair: `plan` computes and conserves, `commit`
+writes atomically. `PROMOTE_FROM` is the two sections a promotion may come from.
+`dormancy_note` is what a demotion says.
+
+`Board::Edit`'s selectors are the part worth reading before touching:
+`select` tries `by_target` then `by_substring`, and reports `no_match` or
+`ambiguous` rather than guessing. `BUDGET_LINE` is the header regex
+`set_declared` rewrites, and `NAMES_NOTHING` is the pair of selectors that
+address nothing at all — an empty string and a bare `/projects`.
+
+# Three refusals that are not politeness
+
+* **A missing file is refused, never created.** `capture` will not create
+  `board.md`; `journal open` will not create `journal/index.md`. An index
+  rebuilt from the one line a verb knows is regeneration wearing an append's
+  clothes.
+* **Text spanning lines is refused, not escaped.** Agent text reaches a board
+  line body or a journal entry body and nowhere else.
+* **A caller-supplied name is contained twice** — one directory segment, *and*
+  resolving inside the bundle, because `projects/<slug>` can be a symlink out.
+  `contained?`, `escaping` and `escape_refusal` are that check; the directions
+  are argued in [containment-directions](/contract/containment-directions.md).
+
+No verb writes a concept body or sets `verified:`.

data/.okf/testing/adding-a-verb.md

@@ -0,0 +1,63 @@
+---
+type: Playbook
+title: Adding a verb, or a check
+description: The nine steps a new `okf pro` surface owes, in order — where the logic goes, which table it joins, which test file it earns, and which catalogue entry the pin will demand.
+generated:
+  by: human:maintainer
+  at: 2026-08-19
+---
+
+# Decide the family first
+
+Four families, and they differ in how they are dispatched, what they may accept
+and what they may do. [capabilities/verbs](/capabilities/verbs.md) has the table.
+
+* a **check** rides a hook event, reads stdin, and answers in the protocol's
+  exit codes — 0 or 2, never 1;
+* a **reader** answers a question about a bundle and takes flags;
+* a **writer** changes a file, and is refused by `Conserve` unless its declared
+  delta is exactly what happened;
+* a **scaffold** verb takes a destination, not a bundle.
+
+Getting this wrong is not stylistic. A reader that skips `parse_flags` reports
+its caller's typo as a broken bundle; a check that returns 1 is read as
+*proceed*.
+
+# The walk
+
+1. **Write the failing test first**, in `test/integration/`, in a file named for
+   the verb — `cli_<verb>_test.rb`, one file per verb and subcommand. Run it.
+   It must fail for the reason you predicted, not because a fixture is missing.
+2. **Put the logic in a module, not in the CLI.** `cli.rb` dispatches, parses
+   flags and prints; the question itself belongs in the module that owns that
+   part of the world. [structure/](/structure/) says which one, and a genuinely
+   new layer earns a new file *and* a line in the concept that owns it.
+3. **Join the right table** in `cli.rb`: `CHECKS` (which puts it in
+   `HOOK_NAMES` automatically), or `READERS`, `WRITERS`, `SCAFFOLD`.
+4. **Add its `USAGE` row**, and the matching row in `OKF::CLI::Pro.help_rows`.
+   The two are separate literals on purpose — reading `USAGE` from the plugin
+   would make every `okf help` load the whole library — and they are held
+   together by a test rather than by discipline.
+5. **Declare its flags** in `FLAGS` if it takes any. Absence means "accepts
+   none", not "is exempt": every reader routes through `parse_flags` either way.
+6. **A writer owes a pure transform.** Compute the new text in `board/edit.rb`
+   or `log/edit.rb` — they cannot touch the disk — declare the added, removed
+   and moved lines, and let `Conserve` refuse the mismatch. See
+   [the-writers](/structure/the-writers.md).
+7. **A check owes a drill** in `test/integration/wrapper_test.rb` if it adds a
+   way for enforcement to be absent. Half the drills there assert a *pass*, and
+   yours should too: a wrapper that refused everything would satisfy every
+   refusal drill in the file. See [drills-over-units](drills-over-units.md).
+8. **Update the catalogue** — [capabilities/verbs](/capabilities/verbs.md) or
+   [capabilities/checks](/capabilities/checks.md). This is not documentation
+   etiquette: `test/unit/bundle_catalog_test.rb` compares those tables against
+   `CLI::USAGE` and `CLI::HOOK_NAMES`, so the suite is red until you do.
+9. **Run the same test unedited.** If it needed editing to pass, it was written
+   after the code and certifies only what the code happens to do.
+
+# What the fixture will do to you
+
+`BundleFixture` is a **client of the code under test** — `write_log` computes
+its snapshot line by calling `Snapshot.line` — so "the suite is green, therefore
+nothing changed" holds only for changes that do not touch what the fixture
+calls. [fixture-is-a-client](fixture-is-a-client.md) is the full argument.

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

@@ -2,6 +2,9 @@
 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.
+generated:
+  by: human:maintainer
+  at: 2026-08-17
 ---
 
 # What a drill is here

data/.okf/testing/fixture-is-a-client.md

@@ -2,6 +2,9 @@
 type: Learning
 title: The bundle fixture is a client of the code under test
 description: The bundle fixture computes its own snapshot line by calling the code under test, so a change to the counters reaches every fixture carrying a log day — which bounds what a green ported suite proves.
+generated:
+  by: human:maintainer
+  at: 2026-08-17
 ---
 
 # Why it calls the code

data/.okf/testing/index.md

@@ -2,3 +2,4 @@
 
 * [drills-over-units](drills-over-units.md) - Every bug in this layer was a gate that passed when it could not do its job.
 * [fixture-is-a-client](fixture-is-a-client.md) - The bundle fixture calls the code under test, so "the ported suite is unchanged proof" has a limit.
+* [adding-a-verb](adding-a-verb.md) - The nine steps a new verb or check owes, in order.

data/.okf/trust/read-owed-rule.md

@@ -2,6 +2,9 @@
 type: Decision
 title: A briefing is owed a read until a human has verified it
 description: §5.3's trust tiers replaced a truthiness test on `verified`, and the four call sites that read the rule have to move together or a briefing falls through all of them.
+generated:
+  by: human:maintainer
+  at: 2026-08-17
 ---
 
 # The rule

data/.okf/trust/scalar-verified.md

@@ -2,6 +2,9 @@
 type: Finding
 title: A scalar `verified:` fails in the worst available direction
 description: The guard fires on the word, the owner approves, and then the reader drops the malformed value — so the concept stays unverified and the To-read line is demanded forever.
+generated:
+  by: human:maintainer
+  at: 2026-08-17
 ---
 
 # The sequence

data/CHANGELOG.md

@@ -4,6 +4,72 @@ All notable changes to okf-pro are documented here. The format follows
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this gem uses
 [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.1.0] - 2026-08-22
+
+### Changed
+
+- **The `okf` floor moves to 2.2.0**, with no change to this gem's own code. The
+  floor tracks the kernel each sibling develops against and may never lag it, so
+  the PR that bumps okf moves every sibling's line — `test/unit/gemspec_test.rb`
+  fails until it does. Nothing here reads a 2.2.0 surface yet; the rule is
+  defensive, and this is the gem where it matters most, since a missing okf
+  method raises inside a check whose crash the hook protocol reads as
+  *non-blocking* — a floor that lags does not error here, it stops gating.
+
+  A floor is part of the published contract, so moving it is a release even when
+  no code changed. Hence a version of its own rather than a line riding along
+  with the kernel's.
+
+## [1.0.1] - 2026-08-20
+
+### Fixed
+
+- **The package metadata follows the `gems/` move and the repository rename.**
+  Two URLs on the package page were about to be wrong at once. `changelog_uri`
+  named `blob/main/okf-pro/CHANGELOG.md`, a path that stopped existing when the
+  four gems moved under `gems/`; `homepage` named `serradura/okf-gem`, and the
+  repository is now **`serradura/okf`** — the name the command has had all
+  along. rubygems.org serves whatever the last release published, so neither
+  corrects itself: only a release republishes metadata, and this is that
+  release. Both land in one round rather than two, which is the whole reason
+  the rename waited for the paths to stop moving.
+
+  `homepage_uri`, `source_code_uri` and `changelog_uri` are all derived from
+  `homepage`, so one line moves four pieces of this gem's metadata. GitHub
+  redirects the old URLs permanently, so anything already published keeps
+  resolving.
+
+### Changed
+
+- **Every concept in the gem's bundle now declares `generated:`.** The actor is
+  the maintainer and the date is read from git with `--follow`, so a rename is
+  not mistaken for authorship — 27 concepts date to the 1.0.0 release and 10 to
+  the structural work after it. `okf lint` on the bundle is clean.
+
+### Added
+
+- **The bundle carries the structure and the catalogue, and a test pins them.**
+  `.okf/structure/` names every file under `lib/`, grouped by the layer that
+  owns it; `.okf/capabilities/` is the catalogue of the sixteen verbs and nine
+  checks this gem already answers; `.okf/testing/adding-a-verb.md` is the walk a
+  new one owes. `test/unit/bundle_catalog_test.rb` 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` or `CLI::HOOK_NAMES`.
+  `AGENTS.md` kept the contract and the commands and now routes here for the
+  rest — its hand-maintained Map of `lib/**` was the thing nothing checked.
+
+### Fixed
+
+- **`AGENTS.md`'s 2.4 floor command pointed at a directory that no longer
+  exists** — `cd /build/okf-pro`, from before the gems moved under `gems/`.
+
+### Changed
+
+- **The okf floor moves to `>= 2.1.1, < 3`** — the kernel this gem develops
+  against released 2.1.1, and the floor tracks what the suite proves against
+  (the gemspec drill enforces equality as the normal state). Nothing here calls
+  a 2.1-only surface; the ceiling is unchanged.
+
 ## [1.0.0] - 2026-08-17
 
 First release. okf-pro begins as a working prototype — a checker carried inside
@@ -184,4 +250,5 @@ every use. This surface answers both.
 - **The `.bin/okf_pro` binary is gone.** `okf pro` is the only door, which is
   what lets the wrapper refuse anything that is not it.
 
-[1.0.0]: https://github.com/serradura/okf-gem/releases/tag/okf-pro%2Fv1.0.0
+[1.0.1]: https://github.com/serradura/okf/compare/okf-pro/v1.0.0...okf-pro/v1.0.1
+[1.0.0]: https://github.com/serradura/okf/releases/tag/okf-pro%2Fv1.0.0

data/README.md

@@ -376,7 +376,11 @@ your day; two people sharing one board is not a supported arrangement.
 Its own knowledge bundle ships inside the gem, at `.okf/` — the non-obvious
 parts, written down: the three ways the plugin seam let an unchecked edit
 through, the check the gate skipped in silence, and why a stray binary on
-`PATH` cannot be caught by reading an exit code.
+`PATH` cannot be caught by reading an exit code. It is also this gem's
+structural documentation and its catalogue of what the verbs and checks already
+answer, so `okf server .okf` inside an installed copy is a working map of the
+code. Which is the format arguing for itself: the bundle you are being handed
+is one the gem reads with its own tools.
 
 ## Licence
 

data/lib/okf/pro/cli.rb

@@ -129,7 +129,7 @@ module OKF
       # Where a friction report goes. It is about okf-pro, not about the
       # adopter's knowledge base, so it is this repository regardless of whose
       # tree the bundle lives in. Nothing is ever filed automatically.
-      ISSUE_REPO = "serradura/okf-gem"
+      ISSUE_REPO = "serradura/okf"
 
       HELP = %w[--help -h help].freeze
 

data/lib/okf/pro/version.rb

@@ -2,6 +2,6 @@
 
 module OKF
   module Pro
-    VERSION = "1.0.0"
+    VERSION = "1.1.0"
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: okf-pro
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.1.0
 platform: ruby
 authors:
 - Rodrigo Serradura
@@ -15,7 +15,7 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '2.0'
+        version: 2.2.0
     - - "<"
       - !ruby/object:Gem::Version
         version: '3'
@@ -25,7 +25,7 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '2.0'
+        version: 2.2.0
     - - "<"
       - !ruby/object:Gem::Version
         version: '3'
@@ -48,6 +48,9 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- ".okf/capabilities/checks.md"
+- ".okf/capabilities/index.md"
+- ".okf/capabilities/verbs.md"
 - ".okf/contract/containment-directions.md"
 - ".okf/contract/exit-codes.md"
 - ".okf/contract/gates-only-at-the-hook-door.md"
@@ -77,6 +80,15 @@ files:
 - ".okf/seam/index.md"
 - ".okf/seam/the-wrapper.md"
 - ".okf/seam/three-fail-opens.md"
+- ".okf/structure/doors.md"
+- ".okf/structure/index.md"
+- ".okf/structure/reading-the-world.md"
+- ".okf/structure/the-gates.md"
+- ".okf/structure/the-guards.md"
+- ".okf/structure/the-recorder.md"
+- ".okf/structure/the-scaffold.md"
+- ".okf/structure/the-writers.md"
+- ".okf/testing/adding-a-verb.md"
 - ".okf/testing/drills-over-units.md"
 - ".okf/testing/fixture-is-a-client.md"
 - ".okf/testing/index.md"
@@ -139,14 +151,14 @@ files:
 - lib/okf/pro/template/seed/gitignore
 - lib/okf/pro/version.rb
 - lib/okf/pro/writes.rb
-homepage: https://github.com/serradura/okf-gem
+homepage: https://github.com/serradura/okf
 licenses:
 - Apache-2.0
 metadata:
   allowed_push_host: https://rubygems.org
-  homepage_uri: https://github.com/serradura/okf-gem
-  source_code_uri: https://github.com/serradura/okf-gem
-  changelog_uri: https://github.com/serradura/okf-gem/blob/main/okf-pro/CHANGELOG.md
+  homepage_uri: https://github.com/serradura/okf
+  source_code_uri: https://github.com/serradura/okf
+  changelog_uri: https://github.com/serradura/okf/blob/main/gems/okf-pro/CHANGELOG.md
   rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths: