okf-pro 1.1.0 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a908d8394cc7ea78e25a744f080813d34eb656b77274e3bb8db4397d222c3950
-  data.tar.gz: 687919c65db7bf0d42bc48f475cd88f636c01aaf87f49443d92c6de0fd434fb9
+  metadata.gz: 1f4b14821d80f4db8b76a6634a53b03fa87d8f04a279c197ed70bcfecb4e5ce1
+  data.tar.gz: 0ccde1c91b1e1156265e3a380c3c3ed6484cd66a70426bb3ff02bc761ad0ee1c
 SHA512:
-  metadata.gz: '0589ad1bd8edb04b767044692d20b271614fe37d60f598fe1b51ba436384142049da27d94d8281df54b0a485b658751e7ef2fe3d4c84a292b4593a61502d6c87'
-  data.tar.gz: 7afe1c08143bf0524f9deb5ce47e827276b59aa805f62cb65b2be5e5414bb542b1208a4b2a59826443ab1fde4e5680066fd047e6236007afc8b3e1b0e04e7ae3
+  metadata.gz: 90264f22dd742779c0600a9215e2e47c2269dd131e4de7f71d066974044e0dd0d23ba2eb966318b23f4703076dbda8e1a3e91d18d8a1c5c7d5bae08a2fbde4a5
+  data.tar.gz: daf911ed01988929bba82c7f056e94ae73c55f5c4979dbcf91c0c09c34012677b95a6547a1400c775611d02c4eb13ed42696a70cf0abede7377b71ebca7b28d9

data/.okf/capabilities/checks.md

@@ -21,7 +21,7 @@ never blocks, and reports "clean." That failure is [gates-only-at-the-hook-door]
 | `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? |
+| `check-okf` | (composed into `post-edit`) | does the bundle still validate and lint — minus the four findings one edit cannot decide? |
 | `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**) |
@@ -32,6 +32,12 @@ never blocks, and reports "clean." That failure is [gates-only-at-the-hook-door]
 `post-edit` instead, because the bundle read is the expensive part and three
 separate invocations paid for it three times over.
 
+Both of the doors that reach `check-okf` ask it for `scope: :edit`, so the four
+set-scoped findings are withheld there and confessed rather than dropped —
+[the-gates](/structure/the-gates.md) has the argument. `stop-gate` and `audit`
+ask the same questions with the write set complete, which is the only place
+they can be answered.
+
 # What they do when they cannot answer
 
 This is the half that matters, and it is the contract rather than a courtesy.

data/.okf/capabilities/verbs.md

@@ -37,6 +37,16 @@ the two together.
 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.
 
+It does go through `parse_flags`, and for a while it was the only family that
+did not. `--help` therefore reached the verb as its destination, and the
+generator answered the question by running. `setup --help` wrote twenty-five
+seed files into a directory named `--help`. `upgrade --help` rewrote the four
+gem-owned files of whatever repository you were standing in, because `upgrade`
+defaults its destination to the working directory. Both exited 0.
+
+None of the three declares a flag, and none needs a `FLAGS` entry to refuse
+one: absence from that table already means "accepts none".
+
 **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",

data/.okf/log.md

@@ -1,5 +1,28 @@
 # Update Log
 
+## 2026-08-30
+
+* **A per-edit check now only asks what one edit can answer.** Four of
+  `Conformance`'s findings — `broken_link`, `broken_index_entry`, `orphan`,
+  `not_in_index` — are questions about a set of files, and no write order
+  avoids them at the per-edit door: write the index first and its entry is
+  broken, write the concept first and it is the orphan. They are withheld
+  under `scope: :edit`, confessed by count rather than dropped, and asked at
+  the Stop gate and in `audit` where the write set is complete
+  ([structure/the-gates](/structure/the-gates.md)). The Stop gate ran no
+  conformance at all before this, so half the change is an addition rather
+  than a move.
+
+* **The scaffold verbs go through `parse_flags` too, and the catalogue says so.**
+  [capabilities/verbs](/capabilities/verbs.md) described the family by what it
+  does *not* do: no `dir_argument`, because `setup` into an empty directory is
+  the point. That omission read as an exemption from the parser as well, and it
+  was one. `--help` reached the verb as its destination, so the generator
+  answered the question by running. The paragraph now names both halves, and
+  [testing/adding-a-verb](/testing/adding-a-verb.md) step 5 says it too. **A
+  family defined only by its exception gets extended in the direction of the
+  exception**, and the next reader pays for that.
+
 ## 2026-08-19
 
 * **Every concept declares `generated:`.** The dates are read from git with

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

@@ -42,6 +42,24 @@ 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.
 
+**The policy on top is a scope.** Four findings — `broken_link`,
+`broken_index_entry`, `orphan`, `not_in_index`, held in `SET_SCOPED` — are
+questions about a *set* of files asked after one of them. An index entry is
+decided by the concept it names; an orphan by whether anything else links it.
+At the per-edit door the write set is incomplete by definition, and no write
+order avoids that: write the index first and the entry is broken, write the
+concept first and it is the orphan. So `check(target, scope: :edit)` withholds
+those four, and the per-edit door is the only caller that asks for it.
+
+Withholding is not dropping, which is the same clause again. `deferral` says
+how many were withheld and names the two doors that ask them with the write set
+complete — `Closing.stop_gate`, through `Conformance.findings` on the bundle it
+has already parsed, and `Audit`, which never scoped anything and needed no
+change. `findings` takes a bundle and an optional `rel:` rather than a Target
+because neither of those doors has an edited file to be the subject: without a
+`rel` there is no "your edit" and no "elsewhere", and inventing the distinction
+would file every finding under a heading saying somebody else did it.
+
 # Two doors, one set of invariants
 
 `Audit.call` is the CI door. It asks `structure`, `conformance`, `curation`,

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

@@ -39,7 +39,9 @@ its caller's typo as a broken bundle; a check that returns 1 is read as
    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.
+   none", not "is exempt". Every reader routes through `parse_flags` either
+   way, and so does every scaffold verb — that second half cost a release to
+   become true.
 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

data/CHANGELOG.md

@@ -4,6 +4,63 @@ 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.2.0] - 2026-08-30
+
+### Changed
+
+- **The per-edit checks only ask what one edit can decide.** Four of the
+  findings `check-okf` reported are questions about a *set* of files, asked
+  after one of them: `broken_index_entry` and its validator twin `broken_link`
+  are decided by the concept an index names, and `orphan` and `not_in_index` by
+  whether anything else in the bundle links or lists the file. No write order
+  avoids them at that door — write the index first and its entry is broken,
+  write the concept first and it is the orphan — so every one of them there was
+  noise by construction, on the hook that fires on every edit.
+
+  `Conformance.check` takes a `scope:` now. The per-edit door asks for `:edit`
+  and withholds those four; everything else asks for `:all` and is unchanged.
+
+- **The Stop gate asks the four instead**, which is the half of this that is an
+  addition rather than a move: `Closing.stop_gate` ran the snapshot, the board
+  grammar and the pairing invariants and **no conformance at all**. It now runs
+  it over the bundle it has already parsed, so the one-parse-per-Stop pin still
+  holds at one. `okf pro audit` needed no change — it never scoped anything.
+
+### Fixed
+
+- **A withheld finding is confessed, not dropped.** The edit door reports how
+  many findings needed the whole write set and names the doors that ask them,
+  because a gate that quietly stops reporting converts "unchecked" into
+  "checked and fine" — the failure the contract's third clause exists to name.
+  Nothing is said when nothing was withheld: a warning that is always present
+  carries no information.
+
+## [1.1.1] - 2026-08-30
+
+### Fixed
+
+- **`okf pro setup --help` prints the usage instead of running the generator.**
+  The three scaffold verbs read their destination from `argv.shift` and never
+  reached `parse_flags`. The flag was therefore the destination. `setup --help`
+  wrote the twenty-five seed files into a directory named `--help` and exited 0.
+  `upgrade --help` was worse: `upgrade` defaults its destination to the working
+  directory, so it rewrote the four gem-owned files of whatever repository you
+  were standing in.
+
+  A help flag that answers the question by running the verb is the worst shape
+  it can have. This is the one family where the answer is files on disk.
+
+  The fix routes the three verbs through the parser the readers already use.
+  None of them declares a flag, and none gains a `FLAGS` entry. Absence from
+  that table already means "accepts none" rather than "is exempt", so `setup
+  --json` is now a typo the parser names. Before, it was a seeded repository in
+  a directory with a leading dash. `--` still separates a destination from the
+  flags, for the rare path that starts with one.
+
+  The write verbs carried this defect and fixed it: `okf pro capture --help`
+  once appended `- <date> — --help` to the Inbox. The scaffold verbs are the
+  last family nobody had checked for it.
+
 ## [1.1.0] - 2026-08-22
 
 ### Changed
@@ -250,5 +307,8 @@ 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.2.0]: https://github.com/serradura/okf/compare/okf-pro/v1.1.1...okf-pro/v1.2.0
+[1.1.1]: https://github.com/serradura/okf/compare/okf-pro/v1.1.0...okf-pro/v1.1.1
+[1.1.0]: https://github.com/serradura/okf/compare/okf-pro/v1.0.1...okf-pro/v1.1.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/lib/okf/plugin.rb

@@ -75,8 +75,6 @@ module OKF
       # rather than swallowed — `okf/pro.rb` refuses an under-floor Ruby with
       # `exit 2`, and a rescue that turned that refusal into an error report
       # would be the fail-open this method exists to close.
-      #
-      # rubocop:disable Lint/RescueException
       def call(argv)
         verb = argv.first.to_s
 
@@ -93,10 +91,9 @@ module OKF
         status.is_a?(Integer) ? status : blocked("returned #{status.inspect} instead of an exit status")
       rescue ::SystemExit
         raise
-      rescue ::Exception => e
+      rescue ::Exception => e # rubocop:disable Lint/RescueException
         blocked("#{e.class}: #{e.message}")
       end
-      # rubocop:enable Lint/RescueException
 
       private
 

data/lib/okf/pro/cli.rb

@@ -21,7 +21,7 @@ module OKF
         "guard-verified" => ->(event) { Guards.guard_verified(event) },
         "journal-guard" => ->(event) { Guards.journal_guard(event) },
         "shell-guard" => ->(event) { ShellGuard.check(event) },
-        "check-okf" => ->(event) { Conformance.check(Target.for(event)) },
+        "check-okf" => ->(event) { Conformance.check(Target.for(event), scope: :edit) },
         "cap-check" => ->(event) { Budget.cap_check(Target.for(event)) },
         "reconcile-search" => ->(event) { Reconcile.search(Target.for(event), event) },
         "post-edit" => ->(event) { CLI.post_edit(event) },
@@ -154,7 +154,7 @@ module OKF
         # covers count — an Edit to a concept body is judgment and always will
         # be, and counting it would report the system working as friction.
         Friction.record(target.root, "edit", target.rel) if target && Friction.covered_path?(target.rel)
-        Conformance.check(target) + Budget.cap_check(target) + Reconcile.search(target, event)
+        Conformance.check(target, scope: :edit) + Budget.cap_check(target) + Reconcile.search(target, event)
       end
 
       def run(argv, stdin: $stdin, stdout: $stdout, stderr: $stderr)
@@ -795,6 +795,18 @@ module OKF
       end
 
       def scaffold(verb, argv, stdout: $stdout, stderr: $stderr)
+        # The one verb group that used to skip the parser, and the one where
+        # skipping it was worst: `--help` became the destination, so asking
+        # what the generator does ran it, into a directory called `--help`.
+        #
+        # No `FLAGS` entry, deliberately — absence already means "accepts
+        # none", and `parse_flags` refuses an undeclared flag either way. An
+        # empty entry would say these three verbs were considered and given
+        # nothing, which is a distinction this table does not draw for `audit`
+        # or `records` either.
+        options = parse_flags(argv, verb, stdout, stderr)
+        return options == :handled ? PASS : BLOCK unless options.is_a?(Hash)
+
         dest = argv.shift
 
         unless argv.empty?

data/lib/okf/pro/closing.rb

@@ -39,7 +39,8 @@ module OKF
         # check below — this gate runs on every Stop, and it used to pay for
         # both twice.
         board = Pro.read_text(File.join(root, "board.md"))
-        concepts = ::OKF::Bundle::Reader.read(root).concepts
+        bundle = ::OKF::Bundle::Reader.read(root)
+        concepts = bundle.concepts
 
         msgs = []
         snap = Log.snapshot_line(Pro.read_text(File.join(root, "log.md")), today.to_s)
@@ -57,6 +58,11 @@ module OKF
         # just verified would agree with itself about a deadline it cannot
         # see. The unreadable line is a refusal, not a rounding error.
         msgs.concat(Board.grammar(board).map { |m| "— board: #{m}" })
+        # The four findings the per-edit door withheld, asked where the write
+        # set is finally complete. `Conformance` takes the bundle this gate has
+        # already parsed rather than a Target: there is no edited file here to
+        # be the subject, and a second read would break the one-parse pin.
+        msgs.concat(Conformance.findings(bundle).map { |m| "— #{m}" })
         msgs.concat(Pairing.failures(root, board: board, concepts: concepts))
         return [] if msgs.empty?
 

data/lib/okf/pro/conformance.rb

@@ -6,12 +6,36 @@ module OKF
     # answer the same questions at the cost of two interpreter boots per edit;
     # the analyzers are pure and take the bundle directly.
     module Conformance
+      # The four findings that are questions about a SET of files, not about
+      # the one just written. An index entry is decided by the concept it
+      # names; an orphan by whether anything else in the bundle links it. At
+      # the per-edit door they are therefore answered against a write set that
+      # is incomplete by definition — the concept an index will list does not
+      # exist yet while the index is being written, and no write order avoids
+      # that, because the reverse order makes the concept the orphan.
+      #
+      # Three are the linter's and one is the validator's. They are one list
+      # because they share a property, not a producer.
+      SET_SCOPED = %i[broken_link broken_index_entry orphan not_in_index].freeze
+
       module_function
 
-      def check(target)
+      # `scope:` is `:all` — every question, for the doors that see the whole
+      # write set — or `:edit`, which withholds the four above and says how
+      # many it withheld.
+      def check(target, scope: :all)
         return [] if target.nil?
 
-        result = ::OKF::Bundle::Validator.call(target.bundle)
+        findings(target.bundle, rel: target.rel, scope: scope)
+      end
+
+      # The same questions asked of a bundle that is already parsed, and of no
+      # file in particular. The Stop gate holds one parse and must not pay for
+      # a second — `closing_test.rb` pins the count at one — and it is asking
+      # about the write set rather than about an edit, which is why `rel:` is
+      # optional here and required nowhere.
+      def findings(bundle, rel: nil, scope: :all)
+        result = ::OKF::Bundle::Validator.call(bundle)
         unless result.valid?
           lines = result.errors.map { |e| "  #{e[:path]}: #{e[:message]}" }
           return [ "okf validate failed after your edit:\n#{lines.join("\n")}" ]
@@ -34,7 +58,8 @@ module OKF
         # They warn rather than refuse: §9's separation is the kernel's, and a
         # gate that turned the validator's warnings into errors would be
         # overruling it from outside.
-        soft = warn_lines(result.warnings)
+        soft_warnings, deferred = sift(result.warnings, scope)
+        soft = warn_lines(soft_warnings)
 
         # WHAT THIS GATE RUNS, AND WHY IT SAYS SO.
         #
@@ -63,9 +88,12 @@ module OKF
         # `skipped_checks` is then empty, and `confession` below is 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.
-        report = ::OKF::Bundle::Linter.call(target.bundle, today: Date.today, except: [ :stale ])
-        notes = confession(report) + soft
-        return notes if report.healthy? && notes.empty?
+        report = ::OKF::Bundle::Linter.call(bundle, today: Date.today, except: [ :stale ])
+        lint, held = sift(report.warnings, scope)
+        deferred += held
+
+        notes = confession(report) + deferral(deferred) + soft
+        return notes if lint.empty? && notes.empty?
 
         # Warnings only. Lint's `:info` findings are observations, and a gate
         # that refuses on an observation stops being read as a refusal.
@@ -79,16 +107,46 @@ module OKF
         # pre-existing warning elsewhere used to arrive under the heading
         # "your edit" on every edit in the bundle, and a gate that blames
         # you for what you did not do is a gate people switch off.
-        mine, theirs = report.warnings.partition { |w| same_file?(w[:path], target.rel) }
         parts = notes
-        parts << "okf lint flagged your edit:\n#{format_warnings(mine)}" unless mine.empty?
-        unless theirs.empty?
-          parts << "okf lint findings elsewhere in the bundle — pre-existing, or a neighbour " \
-                   "your edit affected:\n#{format_warnings(theirs)}"
+        if rel.nil?
+          # No edit to be blamed for or exonerated from. The Stop gate asks
+          # about the write set, so "yours" and "elsewhere" are not a
+          # distinction it can draw, and pretending otherwise would file every
+          # finding under a heading that says someone else did it.
+          parts << "okf lint findings across the bundle:\n#{format_warnings(lint)}"
+        else
+          mine, theirs = lint.partition { |w| same_file?(w[:path], rel) }
+          parts << "okf lint flagged your edit:\n#{format_warnings(mine)}" unless mine.empty?
+          unless theirs.empty?
+            parts << "okf lint findings elsewhere in the bundle — pre-existing, or a neighbour " \
+                     "your edit affected:\n#{format_warnings(theirs)}"
+          end
         end
         [ parts.join("\n") ]
       end
 
+      # Splits a warning list into what this scope answers and a count of what
+      # it withheld. The count is what `deferral` confesses; the findings
+      # themselves are not carried, because the door that can answer them
+      # recomputes them rather than trusting a hand-off.
+      def sift(warnings, scope)
+        return [ warnings, 0 ] unless scope == :edit
+
+        kept, held = warnings.partition { |w| !SET_SCOPED.include?(w[:check]) }
+        [ kept, held.size ]
+      end
+
+      # Withholding is not dropping, and the difference has to be audible. A
+      # gate that silently stopped asking four questions would have converted
+      # "unchecked" into "checked and fine" — the one failure this file's
+      # whole design is against.
+      def deferral(count)
+        return [] if count.zero?
+
+        [ "#{count} finding(s) need the whole write set and were deferred to the Stop gate " \
+          "and `okf pro audit`, which see every file this edit will be part of." ]
+      end
+
       # What the linter did not run, said out loud. Empty in normal operation
       # (see the call above); non-empty means okf grew a check this gate does
       # not know how to supply, and the right answer then IS to stop — an

data/lib/okf/pro/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: okf-pro
 version: !ruby/object:Gem::Version
-  version: 1.1.0
+  version: 1.2.0
 platform: ruby
 authors:
 - Rodrigo Serradura
@@ -174,7 +174,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.16
+rubygems_version: 4.0.10
 specification_version: 4
 summary: 'A profile of OKF: one opinionated shape of knowledge bundle, and the gates
   that hold it there. Structure for making things happen.'