okf-pro 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 89c3d1c35f2504c135c9875a57050aac3288610a5bb812b067faf1284905ab5b
+  data.tar.gz: 8d25d56ce3601cc0fd16e72b6ad43c358b69ee859baac16d0abcb855171cbc64
+SHA512:
+  metadata.gz: 4f17f3f09f2aac6ceb618bcfb0e871c51cf55cc62b701b55b57154ff10b27c02fa84bdc09cc6b38759113f6536afd7246c74e2a3b4233c202c69b59df6a563b1
+  data.tar.gz: d9487c17f613c163b49283b6a626a3e74f0133eafcf1231bd9266d21237573d0d8f799fa4a637da6bda9379e2013d00454979d4be4acea908dd57555072fd774

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

@@ -0,0 +1,107 @@
+---
+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.
+---
+
+# The rule
+
+Every gate reads through `Pro.read_contained`, which resolves the path and
+refuses one whose symlinks leave the bundle root. A `board.md` symlinked out is
+not this bundle's board; a journal entry reached from outside is not this
+bundle's record of a day.
+
+That much is uniform. What happens *next* is not, and the divergence is the
+decision worth recording — because "handle it consistently" is the instinct, and
+here it would be wrong four times over.
+
+# The four answers
+
+| Site | On escape | Why that direction |
+|---|---|---|
+| `Target#read` | **raises** | The caller already proved the file exists, so an escape is a real containment failure. `CLI.run`'s dispatch rescue turns it into a refusal, which is the correct answer to something outside the bundle pretending to be inside it. |
+| `Budget` (dormancy) | **reads as empty** | Dormancy is a question, not a gate. An unreadable entry means *no evidence of work*, which keeps the question being asked — the conservative direction for a prompt that costs nothing to answer. |
+| `Pairing.closed?` | **reads as open** | A closure marker reached only through a symlink is not one anyone may rely on. Open is the safe answer: an open project keeps its board line, and a closed one loses it. |
+| `Writes.close` (the marker) | **refuses** | The write door, and the same reasoning arrives at a refusal: a marker written outside the bundle is a stranger's file edited to satisfy a checker that will not read it back. |
+
+Read the column right to left and the rule generalises: **pick the direction
+that leaves the demand visible.** A refusal, a dormancy question and a retained
+board line are all states a person will notice. Their opposites — a silent pass,
+a project that stops being asked about, a board line quietly removed, a closure
+marker on a file this bundle never reads — are all states nobody finds out
+about.
+
+# The read door and the write door are two decisions
+
+The table above was written about reads, and that was the whole of the miss.
+`Pairing.closed?` refused to read a project index reached through an escaping
+symlink and answered *open*; `Writes.close` read and rewrote **the same path**
+with the uncontained pair, `Pro.read_text` and `Scaffold.write_atomically`. So
+`okf pro close escapee` put `— closed <date>` on somebody else's `index.md`,
+exited 0, and left `okf pro audit` reporting the project as neither on the board
+nor closed. Run twice it appended a second marker, so it was unbounded as well
+as wrong.
+
+Two things follow, and the second is the one worth carrying:
+
+* **A containment decision belongs to a call site, not to a file.** The checker
+  and the writer touch one path and are two sites; deciding once and assuming
+  the other inherited it is how the strictest door and the loosest end up on
+  the same `index.md`.
+* **Contain the leaf, not the directory holding it.** The first fix asked the
+  question of `projects/<slug>/`, which left the case one level down: an
+  `index.md` symlinked out of a perfectly contained directory is read by
+  `Pro.read_text`, which follows the link, and written back by `File.rename`,
+  which does not — so the marker was computed from a stranger's title and
+  landed as a real file *inside* the bundle, and the checker went on refusing
+  to read the path it was written from. Containing the leaf covers both, since
+  a directory that escapes takes every path under it with it.
+* **Every file the verb writes, not the one the bug was reported against.**
+  The leaf fix still only guarded `projects/<slug>/index.md`, and `board.md`,
+  `log.md` and `journal/index.md` are rewritten by exactly the same read-and-
+  rename pair: `okf pro capture` read a stranger's board through a link,
+  appended a line and renamed a temp over it, so the link became a real file
+  holding content the bundle never owned. A containment fix that stops at the
+  path in the report is a fix for the report, not for the class — `Writes`
+  now asks the question in one helper and every verb names the files it
+  touches.
+* **The two doors must agree about the same path.** They may reach different
+  *answers* — the checker says open, the writer refuses — but those two are the
+  same verdict seen from either side, and it is the direction that leaves the
+  demand visible. A pair that disagrees is worse than either alone: the write
+  lands and the check then denies it happened.
+
+Nothing enforces the pairing. It is asked at review, the way this file's rule
+already is, and the question is the same one: *what does this do when it cannot
+answer?*
+
+# Contain against the bundle, not against a root invented from the path
+
+`Pairing.closed?` derived its root as `dirname(dirname(index_path))`, which is
+`<bundle>/projects` — so `SafeRead` refused any project index whose realpath
+left `projects/`, including one that never leaves the *bundle*. A project
+legitimately archived behind a symlink (`projects/beta -> ../archive/beta`) read
+as open forever, and the audit demanded a board line for work closed months ago.
+
+The rule this page states is about **the bundle**, and every caller already held
+it. A containment check that computes its own root is checking a boundary
+nobody drew: it refuses inside the line it was meant to draw, and the direction
+of that error is the one this page warns about from the other side — a demand
+raised against a person who has already done the work is how a gate teaches
+people to stop reading it.
+
+# The one place it is deliberately absent
+
+`BundleRoot.root_index?` has no root to contain against; it is the code
+*deciding* what the root is. A raise there would be a permanent lockout, and a
+rescue answering "not a root" would mis-root the bundle and disarm the journal
+guard — so it reads plainly, and the comment there says why.
+
+# Why `.scrub` is still ours
+
+`SafeRead.read!` tags the encoding without validating it. One invalid byte
+anywhere then raises out of the first regex that touches the string, and that
+exception exits 1 — which the hook protocol reads as *proceed*
+([exit-codes](/contract/exit-codes.md)). The scrub is not tidiness; it is the
+difference between a gate that runs and a gate that lets the edit through while
+appearing to have run.

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

@@ -0,0 +1,42 @@
+---
+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.
+---
+
+# What the protocol actually reads
+
+Claude Code's hook protocol reads **0** as pass and **2** as block. Every other
+exit code — including **1** — is a non-blocking error: the message is surfaced
+and *the tool call proceeds*.
+
+That is the whole reason this gem exists in the shape it does. A crash is a
+pass, from the protocol's side. An interpreter that will not start is a pass. A
+`LoadError` is a pass. Any defect that produces a code other than 2 is a defect
+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
+is never returned. Every other verb keeps the convention.
+
+| Verb | 0 | 1 | 2 |
+|---|---|---|---|
+| `hook <check>` | pass | *never* | block, crash, misconfiguration |
+| `audit`, `records` | clean | findings | usage, or could not run |
+| `snapshot`, `unverified` | printed | — | usage, or no bundle |
+| `setup`, `upgrade`, `skill` | wrote or staged | — | usage, or refused |
+
+# Why a crash inside `audit` is 2 and not 1
+
+`audit` runs in CI, where 1 already means "your bundle has findings". If a crash
+also exited 1, a pipeline could not tell *your bundle is broken* from *the
+checker is broken* — and the second one is the case where the green runs either
+side of it mean nothing. So 1 means findings and nothing else, and a crash exits
+2 with a named cause.
+
+The report-only verbs take this further: they have no findings code at all. A
+non-empty `unverified` list is the truth about a corpus, not a defect in it, and
+an exit code that called it a failure would pressure toward the one lie the
+whole system guards against.

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

@@ -0,0 +1,39 @@
+---
+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.
+---
+
+# The whitelist
+
+`HOOK_NAMES` is `CHECKS.keys` plus `session-context`, and nothing else. The CI
+verbs — `audit`, `records`, `snapshot`, `unverified` — are deliberately not in
+it, so `okf pro hook audit` is a refusal rather than a run.
+
+They read like checks. They ask the same invariants, they live in the same CLI,
+and an earlier version of this checker put all of them in one flat list of
+accepted names.
+
+# Why that list was a fail-open
+
+A CI verb takes a **directory**. A hook check takes an **event on stdin**.
+Dispatch one from the hook door and it never reads the event at all: it inspects
+whatever bundle it resolves, finds nothing wrong with a tree the edit has not
+touched yet, and exits 0.
+
+Exit 0 at the hook door means *the gate ran and found nothing*. So a misspelling
+in `settings.json` that happened to land on a CI verb would disarm that gate
+permanently, and the only evidence would be a hook that never once complained —
+which is indistinguishable from a bundle that was always clean.
+
+That is the contract's third clause ([no check fails
+silent](/contract/the-contract.md)) broken by the dispatcher rather than by a
+check, and it is why the refusal names the distinction out loud instead of just
+saying "unknown check": *the CI verbs are not gates and would report clean
+without reading the event at all.*
+
+# The same reasoning, one door along
+
+`okf pro hook --help` is refused for the identical reason. Help exits 0, and a
+`settings.json` that reached a help branch would be a gate switched off in
+silence. It exits 2 and points at `okf pro --help`, where help actually lives.

data/.okf/contract/index.md

@@ -0,0 +1,10 @@
+# Contract
+
+The three clauses, and what each costs when it is broken.
+
+* [the-contract](the-contract.md) - Blocking checks fail closed, feedback checks fail loud, no check fails silent.
+* [exit-codes](exit-codes.md) - Why `hook` reads only 0 and 2, and why `audit` never spells a crash as 1.
+* [gates-only-at-the-hook-door](gates-only-at-the-hook-door.md) - A CI verb accepted as a check name reports clean without reading the event.
+* [containment-directions](containment-directions.md) - An escaping path is refused, ignored, or read as open — one decision per call site.
+* [telemetry-does-not-lie](telemetry-does-not-lie.md) - The third clause applied to the friction recorder, which is not a check and still may not report an uncounted zero.
+* [silent-skips](silent-skips.md) - The third clause broken by the checker itself, on its own gate path.

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

@@ -0,0 +1,78 @@
+---
+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.
+---
+
+# What was measured
+
+On this gem's own gate path, before the fix:
+
+```
+skipped_checks on the gate path: [:expired, :stale]
+healthy? true
+```
+
+`Bundle::Linter.call(bundle)` with no options cannot run `expired` (it has no
+clock) or `stale` (it has no cutoff). Seven of the nine blocking checks ran, the
+gate reported clean, and nothing said so — [the third clause](/contract/the-contract.md)
+broken by the checker itself, in the one place nobody can notice.
+
+okf 2.0 confesses it in `stats[:skipped_checks]`, a field added for a reader
+exactly like this one. The gate discarded it.
+
+# Why relaying the confession is not the fix
+
+The obvious repair — return the confession as a refusal — makes the gate block
+every edit in every bundle until someone supplies a cutoff. A gate that refuses
+constantly is a gate switched off within a day, which is the same outcome by a
+slower route.
+
+The fix is to leave nothing skipped:
+
+* `today:` is supplied, so `expired` runs. It is `:info`, so this adds no
+  refusal — it removes a silence.
+* `stale` is excluded **in source**, with the reason beside it: it asks
+  "untouched since when?", and this gem has no cutoff policy and no business
+  inventing one. An excluded check is the opposite of a silently skipped one.
+
+`skipped_checks` is then empty in normal operation, which turns the confession
+into a live guard rather than a formality: the day okf adds a third clock-gated
+check, this gate reports it instead of quietly not running it.
+
+# The general shape
+
+A field that reports what did not happen is worthless to a consumer that
+discards it. When a dependency offers one, the question is not whether to log
+it — it is what state makes it non-empty, and whether that state is one the
+caller can act on.
+
+# The same shape, at three more doors
+
+All three were found the same way and are the same failure: a checker
+reporting clean over something it had not looked at.
+
+**The CI door dropped half of what the validator said.** `Audit.conformance`
+returned early on `valid?`, so `result.warnings` went in the bin while the hook
+door reported them at length. A scalar `verified: human:rod` is *conformant* —
+so the attestation guard asks, the owner approves, the reader then drops the
+malformed value, and the trust tier stays `unverified` forever. Caught at the
+agent's tool boundary and waved through by CI and by `pre-commit`, which are the
+two doors an edit made in an **editor** actually passes. Two doors asking one
+question may not answer differently about one bundle; the severity was never the
+disagreement, the silence was.
+
+**A whitelist fails open on every letter it does not name.** The append-only gate
+asked git for `--diff-filter=MDR`. Replacing a committed past day with a symlink
+stages as `T`, a typechange — not `M`, not `D` — so the gate reported
+"append-only" and the commit destroyed the one artefact nobody can reconstruct.
+A whitelist's default answer for anything unenumerated is *pass*, which makes the
+set something to justify rather than inherit: `MDRT`, with the reason beside it.
+
+**And the clause above was kept at one door and broken at the other.** The whole
+argument at the top of this page — supply the clock, exclude `stale` in source,
+assert the residue — was applied to the hook door and never to `okf pro audit`,
+which called `Linter.call(bundle)` bare and printed `clean.` over `expired` and
+`stale`. A lesson recorded against one call site is not a lesson applied; when
+this page said "the gate", there were three of them, and the fix has to be asked
+of each. The residue is now asserted at both.

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

@@ -0,0 +1,218 @@
+---
+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.
+---
+
+# What it is
+
+`Friction` records the moments an agent did by hand something an `okf pro` verb
+could have done: a markdown write inside the bundle arriving through Bash, and
+an Edit or Write whose target is `board.md` — that one path and no other, for
+the reason *The prescribed path is not friction* gives below. It is the only
+thing in this gem that is neither a gate nor a report: it exists so that
+*"which verb is missing?"* is answered by evidence rather than by the
+maintainer's imagination.
+
+Two design constraints shaped it, and neither is about telemetry:
+
+* **No new hook event.** `.claude/settings.json` is a *seeded* file
+  ([scaffold/ownership-not-subject](/scaffold/ownership-not-subject.md)), so a
+  new hook registration never reaches an adopter through `okf pro upgrade`.
+  Friction rides code paths that are already wired, or it does not ship.
+* **It records intent, not outcome.** `shell-guard` fires at PreToolUse, before
+  the owner may deny. That is the right event anyway: the question is what was
+  *attempted* by hand.
+
+# The clause, and why it applies here
+
+> No check ever fails silent.
+
+This is not a check. It refuses nothing and blocks nothing, and a recorder that
+crashed a gate would be a measurement worth less than the thing it measures — so
+every failure path in it is rescued and swallowed. That is the correct trade in
+one direction and a trap in the other: the natural consequence of swallowing a
+failed write is a log that stays empty, a report that says **0**, and a reader
+who concludes the verbs are working.
+
+A count of zero and *"the recorder could not write"* are different states, and
+the whole value of the measurement dies the day they are confused. So:
+
+* a failed write leaves a **marker** beside the log, and
+* an unwritable scratch directory reaches the same verdict on its own — asked
+  directly, because the case where the marker cannot be written either is
+  exactly the case that proves a marker alone is not enough, and
+* a recorded line that will not parse is **counted and confessed**, never
+  dropped, because a corrupted log must not read as a quieter session.
+
+`okf pro friction` and the session banner both say *unknown, not zero* when any
+of that holds. Same shape as [silent-skips](/contract/silent-skips.md): the
+failure was never the missing datum, it was the report that did not mention it
+was missing.
+
+# The prescribed path is not friction
+
+The obvious list of files to watch is board, log, journal day — and it is
+wrong, in the direction that destroys the measurement. `snapshot` deliberately
+has no `--write` (a writer and a checker sharing a code path agree trivially),
+so appending the Snapshot line to `log.md` by hand is *exactly what this gem
+tells you to do*. `journal open` says in as many words that the day's content
+is yours. Recording either counts the system working as evidence that it is
+not: it inflates the banner's request and points the maintainer at verbs that
+already exist and already declined that job.
+
+So the Edit door records `board.md` and nothing else. That is the same rule
+`own_command?` keeps one layer down — **the good path must not count as
+friction** — applied to a path the code prescribes rather than to a command the
+code owns.
+
+That narrowing is also how this page went into the tree **wrong, in the same
+commit as the code it describes**. Its opening paragraph read "board.md,
+`log.md` or a journal day" — the list from before the argument above was made —
+and a concept describing behaviour the code does not have is
+[a-comment-is-not-an-implementation](/design/a-comment-is-not-an-implementation.md)
+at one remove, with a wider readership. The narrowing left `classify`'s other
+two answers unreachable from the edit door and its unit test still green, which
+is the shape [fixture-is-a-client](/testing/fixture-is-a-client.md) records: a
+test calling the function directly proves a branch no user can walk to. One
+covered path means the class a row records **is** that path, so the function is
+gone and the call site passes the path.
+
+The shell door is different and stays broad, because a shell write is a bypass
+whatever it touched: the trust guards read a tool event and a redirect produces
+none. Which is why the report is keyed on the DOOR as well as the file. An Edit
+to the board says a verb went unused; a shell redirect at the board says the
+guards were bypassed, and what covers those is not the same answer.
+
+**And the banner asks the narrower of the two questions.** `okf pro friction`
+reports every row, because a maintainer reading it wants both. The session line
+asks for a *verb*, so it may only count rows a verb would answer — and it
+counted shell rows too, telling the adopter that a verb could have done
+something no verb covers. Worse: `shell-guard` records intent at PreToolUse, so
+the system working exactly as designed — guard fires, owner denies, agent uses
+Edit — still incremented a lifetime counter that then nagged every session until
+`--clear`. A measurement that fires when nothing went wrong is the
+[a-rule-you-can-walk-past](/design/a-rule-you-can-walk-past.md) failure wearing
+telemetry's uniform.
+
+# Sticky, with a way out
+
+The `.unavailable` marker is never cleared automatically, and that is correct:
+one failed write means the count is short by an unknown amount from then on,
+and a recorder that quietly forgave itself would be back to reporting a zero it
+did not count.
+
+Sticky with no way out is a different failure. A momentarily full disk pins the
+answer at *unknown* forever, the banner nags about a week nobody can change,
+and "check that `.tmp/` is writable" is not actionable once the directory is
+perfectly writable and the marker is what is holding the verdict. So the way
+out is explicit, named in the message, and the reader's: `okf pro friction
+--clear`. It touches `.tmp/` and nothing else.
+
+The same reasoning fixes the banner's arithmetic. The log is append-only and
+nothing prunes it, so the count is a **lifetime total** and the line says so —
+"so far", never "last session". A standing warning nobody can act on is the
+failure [a-rule-you-can-walk-past](/design/a-rule-you-can-walk-past.md)
+describes, and naming the reset is what keeps this one a request rather than
+wallpaper.
+
+# Where it points, and what it never does
+
+The banner's friction line addresses the **adopter**, not the maintainer — they
+are the ones paying for a missing verb and the only ones who can say which one
+it is — and `okf pro friction --issue` prints a ready `gh issue create` against
+this gem's repository. **Printed, never run.** Filing an issue is outward-facing
+and irreversible, and a hook that did it unattended would be both without anyone
+asking. If `gh` is absent it prints the URL and the body to paste.
+
+**Nor does it draft a report about nothing.** `--issue` with an empty log
+printed a complete, ready-to-paste issue whose body was an empty list and whose
+title said *0 bundle edit(s)*. Nothing stopped an adopter sending it, and it
+asked the maintainer to act on a measurement that had measured nothing. So a
+count that is genuinely zero prints no issue at all.
+
+Two states are not that, and both still file. *Unknown* is one — "the recorder
+could not write" is something that happened. So is a log whose every line was
+unparseable: zero rows with a positive `unreadable` count is a **corrupted**
+recorder, not a quiet one, and reading the two as the same would have retired
+the report in precisely the case it was most worth sending.
+
+Which then has to hold on **every** surface, and briefly did not: `--issue`
+declined to file for a quiet log and filed for a corrupted one, while the human
+default and the session banner both called a corrupted log "nothing recorded"
+and said nothing at all. A report is only as honest as its least honest surface,
+and the default is the one most people read.
+
+The same page, one more time: the issue BODY branched its whole content on
+`available` and printed only "the recorder could not write, so the counts above
+are unknown" — over a body with nothing above it, under a title that still
+counted the rows. The marker is sticky by design, so one failed write weeks ago
+made every later report evidence-free. A degraded recorder suppresses the
+*claim to completeness*, never the evidence: the rows print, and the caveat says
+the total is a floor.
+
+The same rule caught the issue *title*. It read "N bundle edit(s) done by hand
+that a verb could cover" over a body whose only row said `covered by: Edit or
+Write` — the title is what a maintainer triages on, and it was asking for a verb
+this gem had just decided not to want. It now says what was counted and claims
+nothing about what covers it; the per-row note answers that.
+
+One exclusion keeps the measurement honest: a command matching `okf pro` is not
+recorded. Without it the good path counts as evidence against itself — `okf pro
+snapshot >> .okf/log.md` *is* the prescribed way to add the Snapshot line.
+
+But that exclusion is about a **write**, so two questions had to be separated,
+and getting either wrong breaks the measurement in a different direction.
+
+*Which command wrote?* Asked of the whole string, a mention anywhere suppressed
+the record: `okf pro state && cat notes.md > .okf/board.md` prompted the owner
+and counted nothing — and an agent chaining a read with a write is the commonest
+shape there is, so the under-count sat exactly where the measurement mattered.
+So the question is asked per command: a segment carrying no mutator is nobody's
+write (`cd repo && okf pro promote alpha` is still this gem's), and a mutator in
+a segment this gem does not own is a hand-write whatever else the line says. A
+**pipeline is one command**, not two — splitting on `|` put this gem's own
+redirect target in a segment of its own and recorded `okf pro snapshot | tee -a
+.okf/log.md`, the prescribed move, as friction.
+
+A pipeline being one command is right and is not a licence: `okf pro board |
+sed s/a/b/ > .okf/board.md` starts with this gem and ends by regenerating the
+board, which is failure mode 07 by name. Nothing prescribes piping into a path a
+verb covers — `snapshot` appends to `log.md`, which no verb covers — so an own
+command aimed at `board.md` is friction whatever produced the bytes.
+
+*Is this an invocation, or a mention?* Anchored to the start of a segment, not
+matched anywhere in it. Board lines routinely name these verbs, so a hand-append
+whose CONTENT said `okf pro` excused itself: `echo "- see okf pro docs" >>
+.okf/board.md` was never counted. An assignment prefix is skipped rather than
+breaking the anchor — `$OKF_HOME` is a variable this ecosystem uses, so
+`OKF_HOME=/tmp okf pro snapshot >> .okf/log.md` is the prescribed move wearing a
+prefix, and an anchor that missed it would have made the same mistake in the
+other direction. So is a short, named list of wrappers: `bundle exec okf pro
+snapshot >> .okf/log.md` is *this repo's own* invocation of the prescribed move,
+and an anchor that missed it counted a contributor's first command as friction.
+The list is named rather than open, because an open rule is a way back to
+matching a mention.
+
+Splitting on separators is not shell parsing and may not become it. The residue
+is written down because a bounded error is only bounded if it is: a separator
+inside quoted content splits a command that is genuinely this gem's, and the
+fragment holding the mutator word is read as somebody else's write. That
+over-counts, which is the lesser error — it points a maintainer at a verb that
+already exists, where the under-count it replaced hid the commonest shape there
+is. Neither can refuse anything, and the prompt is still decided from the whole
+command, so the guard's safety is untouched.
+
+# It is telemetry, so it is not state
+
+`okf pro state` is *cheap by contract* — `board.md`, `log.md`, two directory
+globs, no concept parsed — and it briefly read the friction log as well, on
+every call, for a field its human rendering never printed. Two things were wrong
+at once, and the second is the durable one: an append-only file nothing prunes
+had been added to the sources of the verb whose whole promise is that it is
+cheap, and the only reader who could see the field was one asking for `--json`.
+
+Friction is knowledge about the *tooling*, not about the bundle — which is
+already why the log lives in `.tmp/` at the repository root rather than under a
+root `okf validate` walks. `okf pro friction` is the verb that answers it. A
+contract that names its sources is a contract to check when adding one.

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

@@ -0,0 +1,43 @@
+---
+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.
+---
+
+# The three clauses
+
+> Blocking checks fail **closed**. If enforcement is missing or cannot run, the
+> call is refused, loudly. A gate that cannot check must not wave things through.
+>
+> Feedback checks fail **loud**. If enforcement is degraded, it says so in the
+> same channel it would use to refuse.
+>
+> No check ever fails **silent**. A gate that is sometimes absent and does not
+> confess converts "unchecked" into "checked and fine", which is worse than
+> having no gate at all.
+
+# Why the third clause is the one that matters
+
+The first two are ordinary defensive engineering. The third is the reason this
+gem is shaped the way it is, and it is the one people argue with.
+
+The argument against it is that a skipped check is not a failure — nothing went
+wrong, one question simply was not asked. The argument for it is what a reader
+does with the answer. A bundle reported clean is a bundle nobody looks at again.
+If the report was clean because seven of nine checks ran, the reader has been
+handed a false negative wearing the costume of a verdict, and there is no
+subsequent moment at which they find out.
+
+That is worse than no gate, because no gate is a state a person can reason
+about. "We do not check this" produces caution. "We checked and it is fine"
+produces none.
+
+# Where each clause is kept
+
+* Fail closed lives in [the wrapper](/seam/the-wrapper.md), because a Ruby
+  checker structurally cannot refuse on its own absence — something already
+  running has to do it.
+* Fail loud lives in the CLI's refusal messages, which name the cause rather
+  than a code.
+* Fail silent is closed in two places: [the exit codes](/contract/exit-codes.md),
+  and [what the linter did not run](/contract/silent-skips.md).

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

@@ -0,0 +1,85 @@
+---
+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.
+---
+
+# What happened
+
+`ShellGuard::MUTATORS` matched a redirection with `>{1,2}[[:blank:]]*[^|&\s]`,
+and the comment above it said, in as many words, that `>` "is matched only
+where a redirection can sit, so `a > b` in a comparison inside a command is not
+automatically a write."
+
+Nothing in the pattern implemented that. There was no lookbehind, no anchor, no
+position test of any kind — the claim was true of the sentence and false of the
+code, and it had been for the regex's whole life.
+
+In this bundle that is the worst possible miss. `-->` closes the HTML comment
+the skill mandates on every keyed rule and is also mermaid's edge; `=>` is in
+every quoted Ruby hash. So `grep -rn "a --> b" .okf/` — a **read** — was routed
+to the owner as a suspected write, and so was every grep for a rule marker.
+
+# Why that is worse than a gate that is simply absent
+
+The guard's honest verdict is *ask*: it cannot parse shell, so it routes the
+decision to a person who can read the command. That verdict is only worth
+anything while the prompts are rare enough to be read. A guard that fires on
+reads produces a stream of prompts whose correct answer is always "approve",
+and the reflex it trains is approval without reading — which is precisely the
+state where the one prompt that mattered gets approved too.
+
+So the cost is not the false positives. It is that the true positive stops
+being distinguishable from them, and the gate has been retired without anyone
+deciding to retire it. That is failure mode 1 wearing the checker's uniform,
+the same shape [silent-skips](/contract/silent-skips.md) records from the other
+direction.
+
+# The rule
+
+**A comment describing a property the code does not have is worse than no
+comment**, because it is what a reviewer reads instead of the code. Two things
+follow, and both are cheap:
+
+* When a comment asserts a *property* — anchored, bounded, ordered, exhaustive
+  — the test file for that unit must contain the case the property forbids. The
+  arrow cases were unwritable as long as the property was only claimed; writing
+  them is what made the gap visible in one run.
+* When a guard exists to route a decision to a person, its false-positive rate
+  is part of its correctness, not a matter of taste. `test_ascii_arrows_are_not_redirections`
+  exists at the same rank as the drills that prove a refusal, because a guard
+  people switch off refuses nothing at all.
+
+# The same class, at four distances
+
+The regex is the sharpest instance and not the only one. Ordered by how far the
+prose sits from the code it misdescribes:
+
+* **Beside it.** `Board::Edit.set_declared` found the budget header *per line*
+  and put it back with `String#sub`, which searches the whole text — so any
+  earlier line whose tail happened to equal the header matched first, the prose
+  was rewritten and the header left stale. `Conserve` caught the mismatch and
+  refused, which is the system working; but the refusal **named the prose line**,
+  and the board stayed unpromotable until somebody edited a line that was never
+  the problem. A lookup and its inverse have to agree on their unit, and a
+  refusal is only as useful as the thing it points at.
+* **Two definitions away.** `Friction`'s paragraph about reading a class out of
+  a shell command sat above `clear`, fused with `clear`'s own comment, two
+  definitions from `classify_command`. Nothing is wrong with either method; a
+  reader arrives at the wrong one holding the right explanation.
+* **In a message the reader acts on.** The writers share one missing-argument
+  message, and `close` does not take what it offers: a project is one directory
+  segment, so "a substring only one board line carries" is a refusal, and so
+  was `/projects/<slug>/index.md` — the exact link a board line carries and
+  `okf pro board` prints. A message naming what the verb rejects is worse than
+  no message, for the same reason a wrong comment is: it is what the reader
+  acts on instead of the code. Fixed from both ends — the message names one
+  directory segment, and `close` now accepts the third spelling
+  `Board::Edit.by_target` already treated as the same commitment.
+* **In the bundle.** [telemetry-does-not-lie](/contract/telemetry-does-not-lie.md)
+  described a recorder watching three paths while the code watched one — and
+  went into the tree that way *in the same commit as the code*, which is the
+  commit rule in `AGENTS.md` doing the opposite of its job. A concept has a wider readership
+  than a comment and is trusted further, so this is the same failure with the
+  blast radius turned up. Maintaining `.okf/` in the same commit means checking
+  it against the diff, not merely editing it in the same breath.