okf-pro 1.0.0

data/lib/okf/pro/closing.rb

@@ -0,0 +1,206 @@
+# frozen_string_literal: true
+
+module OKF
+  module Pro
+    # Rule 2 — the day ends with a snapshot, and the delta is the signal.
+    #
+    # One of these refuses and one only informs, and that asymmetry is the rule
+    # itself: the snapshot is written at the end (stop-gate refuses without it,
+    # and refuses one that disagrees with the board), and read at the beginning
+    # (session-context puts yesterday's line in front of you before anything
+    # else). A counter nobody compares is wallpaper.
+    #
+    # Both root through BundleRoot.enclosing — the ancestor walk — because
+    # their only input is the session's cwd, and a session parked in a bundle
+    # subdirectory must not be a session whose stop gate silently disengaged
+    # or mistook a directory index for a broken core. resolve() does neither
+    # walk nor discriminate, and was both of those bugs at once.
+    module Closing
+      module_function
+
+      def stop_gate(event, today: Date.today)
+        return [] if event.stop_hook_active?
+
+        root = BundleRoot.enclosing(event.cwd)
+        return [] if root.nil?
+
+        # The precondition is "work happened". A session that read and changed
+        # nothing owes no snapshot, and asking for one would train people to
+        # write a line that means nothing.
+        return [] unless Pairing.dirty_markdown?(root)
+
+        # A bundle missing its skeleton used to slip this gate in silence —
+        # no board, no log, no questions asked. Broken core is the first
+        # refusal, and the only one, because every later check reads the core.
+        broken = Audit.structure(root)
+        return [ "RULE 2 — before stopping:\n#{broken.map { |m| "— #{m}" }.join("\n")}" ] unless broken.empty?
+
+        # One read of the board, one parse of the bundle, shared by every
+        # 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
+
+        msgs = []
+        snap = Log.snapshot_line(Pro.read_text(File.join(root, "log.md")), today.to_s)
+        if snap.nil?
+          msgs << "— log.md has no Snapshot line under #{today}. Append it before stopping — " \
+                  "computed from the bundle as it stands:\n  #{Snapshot.line(root, today: today, board: board, concepts: concepts)}"
+        else
+          # Presence was never the point; agreement is. This runs at stop time,
+          # which is the one moment the calendar cannot make it lie — the same
+          # check in CI would fail on a push nobody made that day.
+          msgs.concat(Snapshot.verify(root, snap, today: today, board: board, concepts: concepts))
+        end
+        # A dated line the counters cannot parse counts as zero, and a zero
+        # is indistinguishable from a quiet board — so the snapshot the gate
+        # 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}" })
+        msgs.concat(Pairing.failures(root, board: board, concepts: concepts))
+        return [] if msgs.empty?
+
+        [ "RULE 2 — before stopping:\n#{msgs.join("\n")}" ]
+      end
+
+      def session_context(event, today: Date.today)
+        root = BundleRoot.enclosing(event.cwd)
+        return nil if root.nil?
+
+        # This channel cannot refuse, so a broken core is said out loud rather
+        # than shown as a suspiciously quiet banner.
+        broken = Audit.structure(root)
+        unless broken.empty?
+          return [ "Bundle at #{root} has a broken core:",
+                   *broken.map { |m| "  — #{m}" },
+                   "The gates cannot read a bundle missing its skeleton; restore it, then `okf pro audit .`." ]
+        end
+
+        lines = state_block(State.call(root, today: today), today)
+        lines.concat(Budget.dormancy_questions(root, today: today,
+          board: Pro.read_text(File.join(root, "board.md"))))
+        lines << REFRESH
+        lines.concat(friction_line(root))
+        lines
+      end
+
+      # The line that actually saves the turns: without it the banner is state an
+      # agent re-reads out of the files the moment it writes anything.
+      REFRESH = "Current as of session start. After you write, refresh with `okf pro state` — " \
+                "do not re-read the files. `okf pro board` lists the lines; `okf pro capture`, " \
+                "`promote`, `demote`, `journal open` and `close` write the mechanical shapes."
+
+      # THE WHOLE BANNER, and there is only one of it.
+      #
+      # The bill is turns × context, not payload size. A measured session spent
+      # nine tool calls and 40.9% of its tool output rediscovering state the gates
+      # already compute — and state delivered here costs no turn at all, because
+      # SessionStart runs whether anyone asks or not.
+      #
+      # Which is exactly why nothing may be said twice. This began as a structured
+      # block appended UNDER three prose lines, and the two overlapped: in flight
+      # and inbox were counted in both, and the snapshot was rendered in both. That
+      # spends the saving the block exists to make, and leaves a reader working out
+      # which of the two numbers is live.
+      #
+      # CHEAP SOURCES ONLY, and that is a constraint rather than a preference.
+      # `State.call`'s default payload reads `board.md`, `log.md` and two directory
+      # globs, and parses no concept. The two counters that would need
+      # `Bundle::Reader.read` are never recomputed here — they arrive inside the
+      # logged Snapshot line, printed whole and labelled by its day.
+      #
+      # Staleness is already covered elsewhere: the stop gate recomputes
+      # independently and refuses a snapshot line that disagrees with the board.
+      def state_block(payload, today)
+        log = payload["log"]
+        open_projects = payload["projects"]["open"]
+        # The board's counters are formatted by `State`, not here: the banner's
+        # whole promise is that it says what `okf pro state` would say, and two
+        # renderings of the same eleven numbers drift into a reader having to
+        # check which one they are looking at.
+        lines = [ State.board_line(payload["board"], "Bundle state at session start —"),
+                  "Log — newest day #{log["newest day"] || "none yet"} · journal for #{today} " \
+                  "#{log["journal today"] ? "open" : "not opened"} · open projects #{open_projects.size}" \
+                  "#{" (#{open_projects.join(", ")})" unless open_projects.empty?}",
+                  snapshot_line(payload["last snapshot"]),
+                  "Read the delta, not the status: a number that moved the wrong way is today's first signal." ]
+
+        # Crack 2's other half: the collision made visible days before it lands.
+        risk = payload["deadlines at risk"]
+        unless risk.empty?
+          lines << "Deadlines within 7d with nothing in flight against them:"
+          risk.each { |line| lines << "  #{line}" }
+        end
+        lines
+      end
+
+      # The logged line WHOLE, with the day it was logged under and the label that
+      # stops a reader taking it for today's. Both halves earn their place: the
+      # twelve counters are what "read the delta" is read against, and two of them
+      # — `unverified briefings` and `projects with 0 concepts` — can only be
+      # recomputed by parsing the corpus, which this banner never does. A second
+      # line restating those two said nothing this one does not.
+      #
+      # Latest by date, not last in the file: `State` reads the log newest-first,
+      # because grepping the whole file for the last hit found its bottom — the
+      # oldest entry — and from day two onward the banner reported the first-ever
+      # counters, inverting the delta it exists to show.
+      def snapshot_line(snap)
+        return "Last snapshot: none yet" if snap.nil?
+
+        "Last snapshot (#{snap["day"]}, not live): #{snap["line"]}"
+      end
+
+      # Addressed to the ADOPTER, not the maintainer, and that is the whole of
+      # its tone: they are the ones paying for a missing verb, and they are the
+      # only ones who can say which one it is. Nothing is ever filed
+      # automatically — `--issue` prints a command a person decides to run.
+      #
+      # A recorder that could not write says so rather than printing a zero. A
+      # zero and "unknown" are different states, and this is the one line in the
+      # banner where confusing them would quietly retire the measurement.
+      def friction_line(root)
+        report = Friction.report(root)
+        unless report.available
+          return [ "Friction: the recorder could not write to .tmp/ at some point, so the count is " \
+                   "unknown rather than zero. `okf pro friction --clear` starts it again." ]
+        end
+
+        # Only what a VERB covers, and that is the difference between a request and
+        # a nag. Shell redirects are recorded too, and `covered_by` answers "Edit or
+        # Write" for them — the trust guards read a tool event and a redirect
+        # produces none — so counting them here claimed 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`. `okf pro friction` shows every row;
+        # this line asks for a verb, so it counts only what a verb would answer.
+        # A log that will not parse is a SHORT count, not a quiet one, and this
+        # is the line where a zero and an unknown must never be confused. Only
+        # the unwritable case was reported; an unreadable one said nothing at
+        # all, which is the same lie one door along.
+        lines = []
+        if report.unreadable.positive?
+          lines << "Friction: #{report.unreadable} recorded line(s) will not parse, so anything " \
+                   "counted here is short by an unknown amount. `okf pro friction --clear` starts " \
+                   "it again."
+        end
+
+        covered = report.events.count { |e| Friction.verb_covered?(e["via"], e["what"]) }
+        return lines if covered.zero?
+
+        # "so far", not "last session", and the difference is not pedantry: the
+        # log is append-only and nothing prunes it, so this is a lifetime total.
+        # A line that framed a cumulative number as this session's would nag
+        # about a week nobody can change, and would keep nagging — which is the
+        # standing-warning failure the whole design is built to avoid. Naming
+        # the reset is what makes the number actionable.
+        lines << "#{covered} bundle edit(s) so far were done by hand that an `okf pro` verb " \
+                 "could do. If one of them should be a verb, please tell the maintainer — `okf pro " \
+                 "friction --issue` prints a ready-to-paste report, and `--clear` resets the count. " \
+                 "It helps more than you think."
+        lines
+      end
+    end
+  end
+end

data/lib/okf/pro/conformance.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+module OKF
+  module Pro
+    # `okf validate` and `okf lint --fail-on warn`, in process. The CLI would
+    # answer the same questions at the cost of two interpreter boots per edit;
+    # the analyzers are pure and take the bundle directly.
+    module Conformance
+      module_function
+
+      def check(target)
+        return [] if target.nil?
+
+        result = ::OKF::Bundle::Validator.call(target.bundle)
+        unless result.valid?
+          lines = result.errors.map { |e| "  #{e[:path]}: #{e[:message]}" }
+          return [ "okf validate failed after your edit:\n#{lines.join("\n")}" ]
+        end
+
+        # §9 forbids the validator from REJECTING a soft problem, so these are
+        # warnings rather than errors — and this gate used to read `errors` only
+        # and drop every one of them on the floor.
+        #
+        # That is not a cosmetic loss. It is where the trust family goes wrong
+        # in the worst direction: `verified: human:rod` written as a scalar
+        # fires the attestation guard (the word is there), so the owner is asked
+        # and approves — and then the reader drops the malformed value, the tier
+        # stays `unverified`, and the To-read line is demanded forever. The
+        # validator says exactly what is wrong — *verified should be a mapping
+        # or a list of mappings* — and surfacing it fixes the whole class in one
+        # line, where an okf-pro-side re-implementation of the grammar would be a
+        # second parser to keep in step with okf's.
+        #
+        # 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)
+
+        # WHAT THIS GATE RUNS, AND WHY IT SAYS SO.
+        #
+        # Two of the linter's checks are clock-gated, and a default
+        # `Linter.call(bundle)` runs neither. Measured on this gate's own path
+        # before this line existed: `skipped_checks: [:expired, :stale]`,
+        # `healthy?: true`. The gate reported clean over two checks it never
+        # ran, and nothing said so — the contract's third clause 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 answer is not to relay the
+        # confession as a refusal — a skipped check is not a finding, and a gate
+        # that blocked every edit until someone supplied a cutoff would be off
+        # within a day. It is to leave nothing skipped:
+        #
+        #   `today:`        the clock `expired` needs. It is `:info`, so this
+        #                   adds no refusal — it removes a silence.
+        #   `except: stale` a decision, stated. `stale` asks "untouched since
+        #                   when?", and this gem has no cutoff policy and no
+        #                   business inventing one — that is curation backlog,
+        #                   which `okf lint` answers when a person runs it and
+        #                   picks a date. An excluded check is excluded here in
+        #                   source, which is the opposite of silent.
+        #
+        # `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?
+
+        # Warnings only. Lint's `:info` findings are observations, and a gate
+        # that refuses on an observation stops being read as a refusal.
+        #
+        # And the lint is bundle-WIDE while this gate fires on one edit, so
+        # the report says which is which. Everything is still reported —
+        # dropping the other files' warnings would hide the edit that
+        # breaks a NEIGHBOUR (delete a concept its index still links, and
+        # the warning lands on the index, not on the file you touched) —
+        # but only the edited file's warnings are called yours. A single
+        # 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)}"
+        end
+        [ parts.join("\n") ]
+      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
+      # unchecked bundle reported as clean is the failure this whole file
+      # exists to prevent, and a loud unknown beats a quiet one.
+      def confession(report)
+        skipped = Array(report.stats[:skipped_checks])
+        return [] if skipped.empty?
+
+        [ "okf lint could not run #{skipped.join(", ")} on this bundle (no cutoff supplied), " \
+          "so those are unchecked rather than clean." ]
+      end
+
+      # The validator's soft findings, which are advice rather than a verdict.
+      def warn_lines(warnings)
+        return [] if warnings.empty?
+
+        [ "okf validate accepted the bundle with #{warnings.size} warning(s) — conformant, but not " \
+          "read the way you meant:\n" +
+          warnings.map { |w| "  #{w[:path]}: #{w[:message]}" }.join("\n") ]
+      end
+
+      def format_warnings(warnings)
+        warnings.map { |w| "  #{w[:path]}: #{w[:message]} (#{w[:check]})" }.join("\n")
+      end
+
+      # Lint reports a concept id, a bundle-absolute link or a path; the
+      # target carries a bundle-relative one. Compared on the stem so the
+      # three spellings of the same file agree.
+      def same_file?(path, rel)
+        stem = ->(s) { s.to_s.downcase.sub(/\A\//, "").sub(/\.md\z/, "") }
+        stem.call(path) == stem.call(rel)
+      end
+    end
+  end
+end

data/lib/okf/pro/conserve.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+module OKF
+  module Pro
+    # The write contract, made enforceable.
+    #
+    #   Additive and targeted, never regenerative. A write verb may append a
+    #   line or edit the line it was given. No verb rewrites a file it did not
+    #   fully derive from that file's own prior contents.
+    #
+    # Failure mode 07 — Agent Drift — is an LLM regenerating a view and dropping
+    # a task, silently: no error, no diff anyone reads, one commitment gone. The
+    # verdict that closed it was "derivation exists as a checker and never as a
+    # generator", and the status quo it was written against is the failure
+    # rather than a defence: today the agent rewrites `board.md` with a heredoc,
+    # which is exactly the silent-drop hazard performed by exactly the actor the
+    # record names.
+    #
+    # So a write verb does not promise to be careful. It states the delta it
+    # intends, computes the new text purely, and hands both to this module,
+    # which compares the LINE MULTISETS and refuses when the actual delta is not
+    # the intended one. A Ruby function that provably cannot drop a line is the
+    # remedy for a heredoc that can, and the difference between the two is that
+    # this one is checked.
+    #
+    # Pure: text in, findings out. No disk, no bundle, no dates.
+    module Conserve
+      module_function
+
+      # `added:` / `removed:` are the lines the caller means to add and take
+      # away. `moved:` is the third shape, and it is invisible to a multiset by
+      # construction — a line that changed sections is neither added nor
+      # removed — so it is asserted directly: still there before, still there
+      # after. Without that, "move it" and "delete it and add it back" and "do
+      # nothing" are the same claim.
+      #
+      # Returns findings; empty means the file may be written.
+      def check(before, after, added: [], removed: [], moved: [])
+        was = counts(before)
+        now = counts(after)
+
+        findings = delta_findings(subtract(now, was), counts_of(added), "added") +
+                   delta_findings(subtract(was, now), counts_of(removed), "removed")
+
+        Array(moved).each do |line|
+          key = normalize(line)
+          findings << "conservation: the line to move is not in the file as it stands: #{key}" unless was[key]
+          findings << "conservation: the line to move is gone from the result: #{key}" unless now[key]
+        end
+        findings
+      end
+
+      # One direction of the comparison, both ways round: what happened and
+      # was not intended, and what was intended and did not happen. Both are
+      # refusals — an edit that did less than it said is as much a lie as one
+      # that did more, and the second is how a promotion silently no-ops.
+      def delta_findings(actual, intended, verb)
+        findings = subtract(actual, intended).map do |line, n|
+          "conservation: #{n} line(s) #{verb} that the edit did not intend: #{line}"
+        end
+        subtract(intended, actual).each do |line, n|
+          findings << "conservation: #{n} line(s) the edit meant to have #{verb} are not: #{line}"
+        end
+        findings
+      end
+
+      # Trailing newline stripped, nothing else. Whitespace inside a line is
+      # content on a board — the leading `- ` is the counters' own grammar —
+      # and normalising it away would let an edit reindent the file past a
+      # guard whose whole job is to notice.
+      def normalize(line)
+        line.to_s.chomp
+      end
+
+      def counts(text)
+        counts_of(text.to_s.lines)
+      end
+
+      def counts_of(lines)
+        Array(lines).each_with_object({}) do |line, acc|
+          key = normalize(line)
+          acc[key] = (acc[key] || 0) + 1
+        end
+      end
+
+      def subtract(left, right)
+        left.each_with_object({}) do |(line, n), acc|
+          surplus = n - (right[line] || 0)
+          acc[line] = surplus if surplus.positive?
+        end
+      end
+    end
+  end
+end

data/lib/okf/pro/event.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+module OKF
+  module Pro
+    # The hook event: the only place this checker parses input it did not write.
+    #
+    # An event it cannot read is enforcement that did not run, so the failure is
+    # recorded rather than swallowed. The first cut rescued the parse error into
+    # an empty hash, every guard read an empty path, and the check passed — the
+    # same shape as the `jq` hole this checker exists to close, rebuilt in Ruby.
+    # Whoever calls it decides what to do with the failure; nobody gets to not
+    # know about it.
+    class Event
+      attr_reader :parse_error
+
+      def self.from_stdin(io = $stdin)
+        new(io.read)
+      end
+
+      def initialize(raw)
+        @data = {}
+        @parse_error = nil
+
+        # The same defense Pro.read_text gives files, applied to the one
+        # input that arrives as a stream: forced to UTF-8 and scrubbed. Stdin
+        # under a bare locale (common in CI and git hooks) arrives tagged
+        # US-ASCII, and a clean em dash in an edit's new_string then raised
+        # out of the very first string operation — above the dispatch rescue,
+        # so ruby exited 1, which the hook protocol reads as NON-BLOCKING.
+        # The guard's own input was the bypass.
+        text = raw.to_s.dup.force_encoding(Encoding::UTF_8).scrub
+        if text.strip.empty?
+          @parse_error = "the hook received no event on stdin"
+          return
+        end
+
+        begin
+          parsed = JSON.parse(text)
+          if parsed.is_a?(Hash)
+            @data = parsed
+          else
+            @parse_error = "the event was #{parsed.class}, not a JSON object"
+          end
+        rescue JSON::ParserError => e
+          @parse_error = "the event was not parseable JSON (#{e.message.split("\n").first})"
+        end
+      end
+
+      def parse_error?
+        !@parse_error.nil?
+      end
+
+      def tool_name
+        @data["tool_name"].to_s
+      end
+
+      def stop_hook_active?
+        @data["stop_hook_active"] == true
+      end
+
+      def tool_input
+        @data["tool_input"].is_a?(Hash) ? @data["tool_input"] : {}
+      end
+
+      def file_path
+        tool_input["file_path"].to_s
+      end
+
+      # Bash's payload. Named for what it is rather than reached for through
+      # tool_input at three call sites.
+      def command
+        tool_input["command"].to_s
+      end
+
+      def cwd
+        raw = @data["cwd"].to_s
+        raw.empty? ? Dir.pwd : raw
+      end
+
+      # Both spellings are read on purpose. Claude Code's Edit/MultiEdit send
+      # `new_string`; the shell shims this replaces only ever looked for
+      # `new_str`, so the `verified:` guard passed every real edit it was built
+      # to stop and only ever refused the synthetic JSON in its own drill. A gate
+      # tested exclusively by the shape it was written against is not tested.
+      def added_text
+        parts = [ tool_input["new_string"], tool_input["new_str"], tool_input["content"] ]
+        edits = tool_input["edits"]
+        if edits.is_a?(Array)
+          parts.concat(edits.map { |e| e.is_a?(Hash) ? [ e["new_string"], e["new_str"] ] : nil })
+        end
+        parts.flatten.compact.join("\n")
+      end
+    end
+  end
+end