okf-pro 1.1.1 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5aa082e7d1ee662bf38b9f16302377b930e9739766dfd24921b5b42867f8c5de
-  data.tar.gz: 30f2caaa6dc5a517dd80ca2b8869946332f7da11513db3ef4d8370da921bc623
+  metadata.gz: 1f4b14821d80f4db8b76a6634a53b03fa87d8f04a279c197ed70bcfecb4e5ce1
+  data.tar.gz: 0ccde1c91b1e1156265e3a380c3c3ed6484cd66a70426bb3ff02bc761ad0ee1c
 SHA512:
-  metadata.gz: 196051ae74e6a129bb82f99b8865d827f9b12ccc27d1b7a51784b2227c412baf867a5df26e13536d7e35b63196cbcb7601638f7f7876fdd7d73734bfb73e17ab
-  data.tar.gz: 9105128a81dfa9e195395ebb3de2759c4c64b9d4f93ce77ed87d5dd36a02299c9d9f642da913f5e0590f62b19af422f6ef710ae29bd91755dfb59a86dd0036f5
+  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/log.md

@@ -2,6 +2,17 @@
 
 ## 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

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/CHANGELOG.md

@@ -4,6 +4,37 @@ 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
@@ -276,6 +307,7 @@ 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

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)

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.1"
+    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.1
+  version: 1.2.0
 platform: ruby
 authors:
 - Rodrigo Serradura