okf 2.1.0 → 2.2.0

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

@@ -0,0 +1,99 @@
+---
+type: Component
+title: The CLI — a Registry, a Base Class, and One File per Verb
+description: The only layer that parses argv, prints and exits; a verb is a class answering four questions about itself and one about a run, and the require order at the bottom of `cli.rb` is the order `okf help` prints.
+tags: [structure, cli, shell, extension-point, plugins]
+generated:
+  by: human:maintainer
+  at: 2026-08-19T12:00:00Z
+resource: lib/okf/cli.rb
+---
+
+# The files
+
+| file | what it owns |
+|---|---|
+| `lib/okf/cli.rb` | the command registry, the dispatcher, plugin discovery, and `okf help` |
+| `lib/okf/cli/command.rb` | the base every verb inherits: streams, refs, shared flags, printers |
+
+And one file per verb, each registering itself at load:
+
+| verb file | verb |
+|---|---|
+| `lib/okf/cli/skill.rb` | `skill` |
+| `lib/okf/cli/server.rb` | `server` |
+| `lib/okf/cli/render.rb` | `render` |
+| `lib/okf/cli/registry.rb` | `registry` and its eleven subcommands |
+| `lib/okf/cli/lint.rb` | `lint` |
+| `lib/okf/cli/loose.rb` | `loose` |
+| `lib/okf/cli/validate.rb` | `validate` |
+| `lib/okf/cli/search.rb` | `search` |
+| `lib/okf/cli/index.rb` | `index` |
+| `lib/okf/cli/dirs.rb` | `dirs` |
+| `lib/okf/cli/stats.rb` | `stats` |
+| `lib/okf/cli/types.rb` | `types` |
+| `lib/okf/cli/tags.rb` | `tags` |
+| `lib/okf/cli/files.rb` | `files` |
+| `lib/okf/cli/references.rb` | `references` |
+| `lib/okf/cli/catalog.rb` | `catalog` |
+| `lib/okf/cli/graph.rb` | `graph` |
+
+**That table's order is the require order at the bottom of `cli.rb`, and the
+require order IS the order `okf help` lists the verbs in.** A test pins the
+result, but the coupling is in the source. What each verb *answers* is the
+[cli](/cli.md)'s group table, pinned against `OKF::CLI.builtins` by
+the same test; the walk a new one owes is
+[adding-a-verb](/testing/adding-a-verb.md).
+
+# What a verb is
+
+A `CLI::Command` subclass answering four questions about itself — `.id`,
+`.group`, `.help_rows`, `.hidden?` — and one about a run: `#call(argv)`,
+returning the exit status. **Privacy is the boundary**: `#call` is the whole
+public surface, so a helper cannot become a verb by accident. `DUCK_TYPE` is
+that contract, checked at registration.
+
+`GROUPS` is the ordering of the sections `okf help` prints; `ROW_FIELDS` is the
+`--fields`/`--except` projection vocabulary.
+
+# What the base class already gives you
+
+Do not re-implement any of these in a verb:
+
+* **refs** — `all_ref?`, and the `@slug` / bare `@` / `@group` resolution every
+  verb inherits, so `okf lint @handbook` works without the verb knowing about
+  registries.
+* **flags** — `json_flags`, `help_flag`, `projection_flags`, `filter_flags`,
+  `depth_flag`. `FILTER_KEYS` is the shared filter vocabulary.
+* **filtering** — `filter_entries`, `dir_scope`, `under_dir?`, and the `--area`
+  deprecation shim in `fold_area`.
+* **printing** — `print_inverted_index` is the shared shape behind `types`,
+  `tags` and friends.
+* **arity** — `no_extras?` is what makes a second bundle an exit-2 usage error
+  for the verbs that take only one. That was a real silent-wrong-answer bug:
+  `okf lint a b` once linted `a`, ignored `b`, and exited 0.
+
+# `CLI.register` is the extension point
+
+Append-only, idempotent by id, duck-type checked — **deliberately the same shape
+as `Search.register`**. Any gem with `okf/plugin.rb` on its load path can
+register a verb and okf finds it, with no edit here and no list of known addons
+(a test greps `cli.rb` to keep it that way).
+
+Discovery is **lazy**: a built-in never triggers a scan, so only an unknown verb
+or `okf help` pays for it. A plugin that raises is skipped and reported on
+stderr, never fatal. `declined` and `register_declined` are how a collision is
+reported rather than silently won.
+
+`PLUGIN_GEM_PREFIX` is `okf-`: **only gems named `okf-*` are loaded**, the same
+convention Jekyll and Vagrant use. Argue it as a convention if it is revisited —
+the threat it closes is thin, and overselling it invites false confidence.
+
+One rule underneath it *is* load-bearing: **naming a gem must never load it.**
+`plugin_gem_name` reads the spec's `full_gem_path` and requires nothing, because
+a refusal that happens after the `require` is not a refusal; a test pins it. A
+path belonging to no gem stays trusted — `ruby -I`, a Gemfile `path:`, a
+checkout — someone put it there.
+
+`seal_builtins!` is the line between what ships and what was installed, and it
+is what `extension?` reads to print the "installed extensions" section.

data/.okf/structure/the-disk-shell.md

@@ -0,0 +1,76 @@
+---
+type: Component
+title: The Disk Shell
+description: Where a directory becomes a Bundle and back — the reader, the atomic writer that validates before it publishes, the folder handle everything above it uses, and the registry.
+tags: [structure, shell, io, registry, atomic]
+generated:
+  by: human:maintainer
+  at: 2026-08-19T12:00:00Z
+resource: lib/okf/bundle/folder.rb
+---
+
+# The files
+
+| file | what it owns |
+|---|---|
+| `lib/okf/concept/file.rb` | one concept as an on-disk handle: read, save, delete, reload |
+| `lib/okf/bundle/reader.rb` | a directory to a `Bundle`, unparseable files kept rather than dropped |
+| `lib/okf/bundle/writer.rb` | a `Bundle` to a directory — locked, validated, then promoted atomically |
+| `lib/okf/bundle/folder.rb` | the on-disk bundle handle every layer above actually holds |
+| `lib/okf/registry.rb` | which bundles a machine or a project knows, addressed as `@slug` |
+
+These are the shell. Everything they call into is pure, and
+`test/unit/boundary_test.rb` keeps the arrow pointing one way.
+
+# Folder is the handle, not a convenience
+
+`Folder.load(dir)` is what the CLI, the server, the TUI and the MCP shell all
+hold. It delegates `validate`, `lint`, `graph`, `skeleton`, `catalog`, `hubs`,
+`directories`, `directory_index`, `stats`, `tag_groups`, `references` and
+`log_entries` to the pure model, and adds only what needs the disk:
+`concept_source`, `reference_files`, `reload`, `save`, and `Folder.label`.
+
+Reach for `Folder`, not `Reader` — the reader is how a folder is built, once.
+
+# The writer publishes or it does not
+
+`Writer#call` takes a lock, writes the whole tree to a temporary path, runs the
+**validator** against it, and only then promotes it into place. A bundle that
+would not validate is never published, and a crash mid-write leaves the old tree
+intact. `AlreadyExistsError` and `ValidationErrorFromResult` are the two
+refusals; `safe_markdown_path!` is the containment check, borrowed from the
+format layer rather than rewritten.
+
+No CLI verb writes a bundle. This is the library API's surface, which is why its
+integration coverage is low *by design*, and why a new verb reaching for it is
+worth a second look — [adding-a-verb](/testing/adding-a-verb.md) says where
+logic belongs instead.
+
+# Registry: two files, one answer
+
+`Registry` is the `@slug` layer. `HOME_ENV`/`DEFAULT_HOME` is the global
+registry under `$OKF_HOME` (default `~/.okf`); `LOCAL_FILE` is the project-local
+`.okf.json` (or the legacy `.okf-registry.json`) that `discover` finds by walking up from the working
+directory. **A discovered local registry replaces the global one outright** — it
+does not merge — and `NO_DISCOVERY_ENV` (`OKF_NO_DISCOVERY=1`) is the escape
+hatch that forces the global one, which is what a test that must not see the
+developer's registry sets. `Registry.load`'s `follow_links:` is the same
+decision one step further: it is true only for the global registry, so a local
+one parses links and never resolves them.
+
+`relative_base` is why a local registry's paths stay relative and the file
+travels with the repository. `Registry#reopen` preserves it; `Registry.new(path)`
+does not, and reaching for the latter is how a reload comes to resolve every
+bundle against the wrong base.
+
+`Link` points the global registry at another registry file; `resolve_links`
+folds that file's bundles in (through `link_slug`, which prefixes only on a
+collision) and `refuse_linked` is the single guard every write goes through —
+here rather than in the CLI, because the server's bundles panel calls these same
+methods. `open_linked` constructs the target with `follow_links: false`, which is
+the whole of the depth rule.
+
+`Group` is a named, recursive set of bundles. `RESERVED_SLUGS` is `all`, because
+`@all` means every bundle and may not be shadowed. `slugify`, `dedupe`,
+`normalize` and `path_shaped?` are the naming rules a `registry set` goes
+through.

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

@@ -0,0 +1,81 @@
+---
+type: Component
+title: The Model
+description: A bundle and its concepts in memory, with no disk and no stdio anywhere in it — plus the four derived views every other layer reads instead of recomputing.
+tags: [structure, model, pure, graph]
+generated:
+  by: human:maintainer
+  at: 2026-08-19T12:00:00Z
+resource: lib/okf/bundle.rb
+---
+
+# The files
+
+| file | what it owns |
+|---|---|
+| `lib/okf/concept.rb` | one concept: frontmatter, body, and every §5 question about it |
+| `lib/okf/bundle.rb` | the set: concepts, reserved files, and the rollups |
+| `lib/okf/bundle/graph.rb` | nodes and edges, plus the type and tag indexes |
+| `lib/okf/bundle/references.rb` | the `references/` inventory and who cites what |
+| `lib/okf/bundle/row_filter.rb` | one predicate for `--type/--dir/--tag/--status/--trust` |
+| `lib/okf/bundle/skeleton.rb` | directories, the arcs between them, and the suggested cut |
+
+All six are **pure**. No `File`, no `Dir`, no stdio — `test/unit/boundary_test.rb`
+fails the build if that changes.
+
+# Concept: the §5 vocabulary lives here
+
+`Concept` is where the spec's provenance model is implemented, and the parts
+worth knowing before adding a field:
+
+* `RESERVED_FILENAMES` and `reserved?` — `index.md` and `log.md` are not concepts.
+* `STATUSES` / `DEFAULT_STATUS` / `effective_status` — §4.1's lifecycle, with the
+  default applied once so no caller has to remember it.
+* `generated`, `generated_at`, `generated_by`, `declared_generated?` — a
+  *declared* provenance, never a derived one.
+* `verified`, `fold_tier`, `shows_trust?` — the trust tiers, and the predicate
+  that decides whether a bundle even has a trust dimension to show. That last one
+  is a single predicate on purpose: a UI that gates a chip one way and a facet
+  another promises rows it will not return.
+* `ISO_DATE`, `ISO_CUTOFF`, `ATTESTED_COMPUTATION`, `HUMAN_ACTOR` — the literals
+  the validator and the linter both read, rather than each spelling them.
+
+`CONCEPT_SCOPED_CHECKS` is the list of lint checks that are about one concept, and
+it is here rather than in the linter because it is a fact about the model.
+
+# Bundle: the rollups every other layer reads
+
+`Bundle` holds `concepts`, `reserved` and `unparseable` — an unreadable file is
+kept as an `Entry` with its error rather than dropped, because a validator that
+silently skips what it could not parse reports a clean bundle.
+
+`catalog`, `stats`, `hubs`, `directories`, `directory_index`, `tag_groups` and
+`paths_by_id` are the derived views. Read one rather than recomputing it: the
+CLI, the server, the TUI and the MCP shell all answer from these, which is what
+keeps four surfaces from disagreeing about the same number.
+
+`okf_version` is what the bundle *declares* (§12), never a literal — the health
+of every downstream v0.1-versus-v0.2 decision depends on that distinction.
+`VIRTUAL_ROOT` is the path a rootless in-memory bundle is contained against.
+
+The two analysers that read all of this are [the-analysers](/structure/the-analysers.md).
+
+# Graph, Skeleton, References, RowFilter
+
+`Graph.build` turns concepts into nodes and their links into edges, with
+`type_index` and `tag_index` alongside. `unlinked_ids` is the orphan set.
+`minimal:` and `body:` are how a caller asks for less than the whole thing —
+the payload the graph page embeds is not the payload `okf graph --json` prints.
+
+`Skeleton` is the directory-level view: `dirs`, `arcs` between them, and
+`suggested_cut` — the weight at which the arc diagram stops being a hairball.
+`cuts_for` maps that back onto concrete edges.
+
+`References` inventories the `references/` folder and the concepts citing each
+file, including the dangling ones.
+
+`RowFilter.matches?` is the *single* predicate behind every `--type`, `--dir`,
+`--tag`, `--status` and `--trust` filter in the CLI, the server and the TUI.
+`shows_trust?` is the same gate `Concept` exposes, reachable from a catalog row.
+A second filter implementation is how two views come to disagree about what
+"matching" means.

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

@@ -0,0 +1,74 @@
+---
+type: Component
+title: The Server and the Page
+description: One ERB template that is the whole UI, served by a Rack app or baked to a file by `render` — plus the hub that mounts many bundles and owns the only writes in the server.
+tags: [structure, server, rack, render, xss]
+generated:
+  by: human:maintainer
+  at: 2026-08-19T12:00:00Z
+resource: lib/okf/render/graph.rb
+---
+
+# The files
+
+| file | what it owns |
+|---|---|
+| `lib/okf/render/graph.rb` | the ERB render — `Graph.static` bakes a file, the same class serves the page |
+| `lib/okf/server/app.rb` | the Rack app for one bundle: the page and its JSON endpoints |
+| `lib/okf/server/hub.rb` | N bundles at `/b/<slug>/`, plus the routes only a set can answer |
+| `lib/okf/server/hub/not_found.rb` | the 404 page: what was asked for, what exists, and the nearest match |
+| `lib/okf/server/runner.rb` | the built-in WEBrick to Rack bridge — no rackup file needed |
+
+The template itself is `graph/template.html.erb` beside `render/graph.rb`, and it
+is ~1,300 lines of inline JS and CSS. Both halves open with a section map; the JS
+one also names the three seams that actually couple the sections
+(`applyGraphFilter`, `setView`, the lazy caches). Read it before editing —
+`grep -n '── '` on the template prints the same list with live line numbers.
+
+# One template, two modes
+
+`Render::Graph.static` bakes a self-contained file with the payload embedded;
+`Server::App` serves the same template and lets the browser `fetch()` bodies on
+demand. **The two modes diverge exactly there** — baked `EMBED` versus fetched
+endpoints — which is why every browser spec runs twice, once against each.
+
+`LAYOUTS` is the five Cytoscape layouts; `MIN_SIZE`/`MAX_SIZE` the node scaling.
+
+# The page stays self-contained, and two XSS defenses hold the line
+
+Only Cytoscape, marked and DOMPurify load from a CDN at boot; Mermaid, Panzoom,
+MiniSearch and the extra layout engines lazy-load on first use. No htmx, no
+bundler, no build step.
+
+Two defenses, and a new render path that skips either one reopens the hole:
+
+* **`json_for_script`** escapes `<` so inlined data cannot break out of its
+  `<script>` — `LT_ESCAPE` is that literal.
+* **`DOMPurify.sanitize(marked.parse(...))`** runs on every fetched body before
+  it reaches `innerHTML`.
+
+# App: the endpoints
+
+`/` is the page; `/node`, `/node/meta`, `/catalog`, `/tags`, `/types`, `/index`
+and `/log` are the JSON it pulls. `SEARCH_ENGINE` is `:index` here — a server
+*can* amortise the build, which is the opposite of the CLI's default — and
+`warm_search` is where that build happens, at boot rather than on the first
+query.
+
+The bundles it serves are loaded through [the-disk-shell](/structure/the-disk-shell.md).
+
+# Hub: many bundles, and the only writes
+
+`Hub` mounts each bundle under `MOUNT` (`/b/<slug>/`) and adds the routes a set
+can answer that one bundle cannot: `GET /search` across all of them, `GET /b/`
+for the listing, and `POST /registry/{default,rename,remove,add}`.
+
+**Those four writes are the only writes in the whole server**, they are off
+unless `writable:`, and they are guarded: `authentic?` and `same_origin?` with a
+`token`, because a page that can rename a bundle is a page a hostile site would
+like to submit a form to.
+
+`Hub::NotFound` is a real page rather than a status code — it names what was
+asked for, lists what exists, and offers the nearest slug by edit distance. It
+carries its own CSS, mark and script because the 404 must render when the
+bundle it was asked for does not exist.

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

@@ -0,0 +1,52 @@
+---
+type: Component
+title: The Skill and Its Installer
+description: The companion agent skill ships from exactly one tree in this gem, and two generated copies elsewhere in the repository are regenerated rather than edited.
+tags: [structure, skill, generated, single-source]
+generated:
+  by: human:maintainer
+  at: 2026-08-19T12:00:00Z
+resource: lib/okf/skill.rb
+---
+
+# The file
+
+| file | what it owns |
+|---|---|
+| `lib/okf/skill.rb` | `Skill.install` — the installer, its `ASSETS` tree, and `Skill::Error` |
+
+`ASSETS` points at `lib/okf/skill/`, and **that tree is the single canonical
+copy of the skill.** `okf skill <dest>` installs from it, so edit it there and
+nowhere else.
+
+`NAME` is `okf`, `SKILLS_DIR` is `skills`, and `nest:` decides whether the
+install lands in a `skills/okf/` subdirectory or directly in the destination —
+`--here` is the flag that turns it off. `force:` overwrites.
+
+# Two generated copies exist, and neither is editable
+
+`plugin/skills/okf` and `skills/okf` at the repository root are *generated*
+copies — the Claude Code plugin's, and the one a generic skill installer reads.
+`rake skill:sync` writes both from this tree and stamps the plugin manifest's
+version.
+
+Two guards fail on drift, both by file list **and** SHA-256 checksum:
+`rake skill:verify`, which `build` depends on, and `test/plugin/sync_test.rb`.
+So a release with a stale copy is impossible rather than a CI failure after the
+fact.
+
+# The markers in the skill text
+
+Guidance lines in the skill carry stable anchors — `<!-- check:<lint-check-id> -->`
+where a deterministic check enforces the point, `<!-- rule:okf-<slug> -->` for
+pure-judgment craft. They render invisibly and sync verbatim into every copy, so
+keep them on the line they annotate when you edit it. They exist so an eval can
+pin a claim and a concept can cite one.
+
+# Loading
+
+The other shell that loads on demand is [the-cli](/structure/the-cli.md).
+
+`skill.rb` is one of the two argv-facing shells that **do not** load with
+`require "okf"` — the CLI is the other. `exe/okf` requires them, and so must any
+test that drives them. An embedding application never pays for either.

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

@@ -0,0 +1,76 @@
+---
+type: Playbook
+title: Adding a Verb, or a Subcommand
+description: The steps a new command owes, in order — the file it lives in, the base class it must not re-implement, the three folders it earns a test in, and the catalogue entry the pin will demand.
+tags: [testing, playbook, cli]
+generated:
+  by: human:maintainer
+  at: 2026-08-19T12:00:00Z
+resource: lib/okf/cli/command.rb
+---
+
+# Before adding one, check it is not already there
+
+Seventeen commands and eleven subcommands already exist, catalogued in
+[cli](/cli.md) and [read-views](/capabilities/read-views.md), and `okf help`
+prints the same list. Most of what a new verb would want is a *flag* on an
+existing view rather than a view of its own: the shared filters and projections
+— `--type/--dir/--tag/--status/--trust` and `--fields/--except` — compose with
+every list already.
+
+# The walk
+
+1. **Write the failing test first**, in `test/integration/cli/`, in a file named
+   for the verb. Run it. It must fail for the reason you predicted — not because
+   a fixture is missing or a regex has a typo, which prove nothing about the
+   behaviour. A test written *after* the fix certifies only the code it was read
+   off.
+2. **One file per verb**, at `lib/okf/cli/<verb>.rb`, registering itself at load.
+   A subcommand family stays in its parent's file, but earns its own *test*
+   file — `registry set` is a surface a user invokes on its own.
+3. **Subclass `CLI::Command` and add nothing it already has.** Refs, the shared
+   flags, `filter_entries`, `print_inverted_index`, `no_extras?` — the list is in
+   [the-cli](/structure/the-cli.md). Re-implementing one of these is how two
+   verbs come to disagree about what `--dir` means.
+4. **`#call` is the whole public surface.** Everything else is private, so a
+   helper cannot become a verb by accident. Answer `.id`, `.group`,
+   `.help_rows`, `.hidden?`.
+5. **Add its `require` to the block at the bottom of `cli.rb`**, in the position
+   you want it to appear in `okf help` — that order *is* the help order, and a
+   test pins the result.
+6. **Decide the arity, explicitly.** If it takes one bundle, `no_extras?` must
+   make a second an exit-2 usage error. If it takes several, it belongs in the
+   `across_bundles/` group with the ones that do.
+7. **Prove it in every folder it has** — `by_dir/`, `by_registry/`, and
+   `across_bundles/` (which for a single-bundle verb means proving the *refusal*).
+   Then exercise the whole surface, not the happy path: every flag once, every
+   output format it offers, every exit code it can return, and the combinations
+   that actually interact.
+8. **Update what describes it.** A new file under `lib/` needs its line in the
+   concept in [structure/](/structure/) that owns its layer, and the verb needs
+   its cell in [cli](/cli.md)'s group table.
+   `test/unit/bundle_catalog_test.rb` fails on either. So does the gem's README,
+   which owes a line for every verb; nothing enforces that one.
+9. **Run the same test unedited**, then read the uncovered lines:
+   `bundle exec rake test:integration`, then diff
+   `coverage/integration/.resultset.json` for the files you changed. Three
+   shapes hide there by habit, because a unit test walked them first: the
+   *second* output format, an *error* branch and the exit code it carries, and
+   *malformed-input* robustness.
+
+# Where the logic goes
+
+Not in the verb. The CLI parses argv, prints and exits; the question belongs to
+the pure model or to an analyser, so that the server, the TUI and the MCP shell
+get the same answer without asking the CLI. If a verb is computing something,
+it is probably a method on `Bundle` that has not been written yet.
+
+New I/O goes in the shell, new logic in the core, and
+`test/unit/boundary_test.rb` fails the build if a pure file forgets.
+
+# The exit codes are a contract
+
+`0` ok, `1` a failing bundle, `2` a usage error. And the older half of that
+contract: **`validate` and `lint` stay separate** — a conformance check may not
+live in lint and a curation finding may not fail validate. See
+[structure/the-analysers](/structure/the-analysers.md).

data/.okf/testing/index.md

@@ -0,0 +1,12 @@
+# Testing
+
+Why the suite is shaped the way it is — integration first, its coverage read as
+a map rather than a score, and the graph page proven in a real browser — is in
+[Design](/design/): [integration-first](/design/integration-first.md) and
+[browser-tests](/design/browser-tests.md).
+
+What is here is the procedure: the ordered walk a new surface owes, ending at the
+checks that will refuse it if a step is skipped.
+
+* [Adding a Verb](adding-a-verb.md) - The steps a new command or subcommand owes, in order.
+* [The test harness](the-harness.md) - One base class for the whole suite, and why the 2.4 floor binds `test/` exactly as it binds `lib/`.

data/.okf/testing/the-harness.md

@@ -0,0 +1,45 @@
+---
+type: Component
+title: The test harness
+description: One base class for the whole suite — plain Minitest plus `test "..."` and block setup/teardown — and it runs on 2.4, so the gem's API floor binds the tests exactly as it binds `lib/`.
+resource: gems/okf/test/test_helper.rb
+tags: [testing, minitest, ruby-floor]
+generated:
+  by: human:maintainer
+  at: 2026-08-19T12:00:00Z
+---
+
+# One base class
+
+Every test in this gem subclasses `OKF::TestCase`, defined in
+`test/test_helper.rb`. It is plain Minitest with two pieces of sugar:
+
+* `test "a sentence" do … end` instead of `def test_a_sentence`, so a failure
+  names the behaviour in prose rather than in snake case;
+* block `setup` / `teardown`, which compose rather than requiring `super`.
+
+Nothing else is the base class. A test that reaches for `Minitest::Test`
+directly loses both and reads unlike its neighbours, which is the whole reason
+the sugar exists — the three siblings each ported the same class for the same
+reason, so the suites read alike across the monorepo.
+
+# It runs on 2.4, so the floor binds it
+
+The suite runs on every supported Ruby, 2.4 included. That makes the
+[Ruby floor](../design/ruby-floor.md)'s forbidden-API list a rule about `test/`
+as much as about `lib/` — a `filter_map` in a test fails the floor container
+exactly as one in a source file does, and RuboCop will not catch either.
+
+SimpleCov is the one exception, and it is conditional rather than absent: it
+needs 2.5+, so `test_helper.rb` loads it inside a `begin`/`rescue` and the suite
+simply runs without coverage where it cannot load. Coverage is a reporting
+convenience; the floor is a contract, and the contract wins.
+
+# What a test may assume about the disk
+
+Fixtures are real directories under `test/fixtures/`, not mocks. A branch that
+no fixture can reach is a branch nobody has ever proven, so the answer to an
+unreachable path is a new fixture rather than a bent assertion — the general
+form of that obligation is `@okf-eco design/how-a-change-is-proven`, and how the
+critical layer is organised is
+[integration first](../design/integration-first.md).