okf-pro 1.0.0

data/lib/okf/pro/friction.rb

@@ -0,0 +1,262 @@
+# frozen_string_literal: true
+
+require "fileutils"
+
+module OKF
+  module Pro
+    # What the verbs did not cover — recorded, never enforced.
+    #
+    # Every verb in this gem is a gate or a report. This one is neither: it
+    # writes down the moments an agent did by hand something a command could
+    # have done, so the question "which verb is missing?" is answered by
+    # evidence instead of by the maintainer's imagination. Two points feed it,
+    # and both are code paths that already run — no new hook event, because
+    # `settings.json` is SEEDED and a new registration would never reach an
+    # adopter through `upgrade`.
+    #
+    # It records INTENT, not outcome. `shell-guard` fires at PreToolUse, before
+    # the owner may deny, so a recorded line means "this was attempted by
+    # hand", which is exactly the question being asked.
+    #
+    # THE THIRD CLAUSE, APPLIED TO TELEMETRY. This is not a check: it neither
+    # refuses nor blocks, and a recorder that crashed a gate would be a
+    # measurement worth less than the thing it measures. But it does not lie
+    # about having counted. A write that fails leaves a marker beside the log,
+    # and an unwritable scratch directory is the same state — both make
+    # `report` answer `available == false`, and the banner says the data is
+    # unavailable rather than printing a zero nobody can distinguish from a
+    # session that used the verbs.
+    module Friction
+      # The scratch directory the seeded `.gitignore` already ignores, at the
+      # REPOSITORY root rather than inside the bundle: this is telemetry about
+      # the bundle, not knowledge in it, and `okf validate` walks every `.md`
+      # under the root.
+      SCRATCH = ".tmp"
+      LOG = "okf-pro-friction.log"
+      MARKER = "okf-pro-friction.unavailable"
+
+      # What `report` hands back. `available` is the honest half: false means
+      # the count is not zero, it is unknown.
+      # `events`, not `entries`: a Struct member of that name overrides
+      # `Struct#entries` — Enumerable's alias for `to_a` — and a reader that
+      # got the Struct's own fields back instead of the recorded lines would
+      # be a silently wrong count, which is the one thing this must not be.
+      Report = Struct.new(:events, :unreadable, :available)
+
+      module_function
+
+      # The repository the bundle sits in. `.okf/board.md` is a bundle under a
+      # repository; a flat root IS the repository. Nothing else distinguishes
+      # them, and the scratch directory belongs to the outer one either way.
+      def scratch_root(root)
+        base = File.expand_path(root.to_s)
+        File.basename(base) == BundleRoot::DIR ? File.dirname(base) : base
+      end
+
+      def log_path(root)
+        File.join(scratch_root(root), SCRATCH, LOG)
+      end
+
+      def marker_path(root)
+        File.join(scratch_root(root), SCRATCH, MARKER)
+      end
+
+      # One line appended, or a marker set. Never raises: the callers are a
+      # PreToolUse guard and a PostToolUse check, and an exception out of
+      # either is an edit sailing through while the gate lies on the floor.
+      def record(root, via, what, detail = nil, today: Date.today)
+        path = log_path(root)
+        FileUtils.mkdir_p(File.dirname(path))
+        entry = { "at" => today.to_s, "via" => via, "what" => what }
+        entry["detail"] = detail if detail
+        File.open(path, "a") { |file| file.puts JSON.generate(entry) }
+        true
+      rescue StandardError
+        mark_unavailable(root)
+        false
+      end
+
+      def mark_unavailable(root)
+        path = marker_path(root)
+        FileUtils.mkdir_p(File.dirname(path))
+        File.open(path, "a") { |file| file.puts Date.today.to_s }
+        nil
+      rescue StandardError
+        # Nothing left to try. `report` reaches the same verdict from the
+        # unwritable directory itself, which is why this may give up quietly.
+        nil
+      end
+
+      # Entries in file order, plus the two things a reader must not be told
+      # by omission: how many lines would not parse, and whether the recorder
+      # was able to run at all.
+      def report(root)
+        events = []
+        unreadable = 0
+        path = log_path(root)
+        if File.exist?(path)
+          Pro.read_text(path).each_line do |line|
+            next if line.strip.empty?
+
+            parsed = parse(line)
+            parsed ? events << parsed : unreadable += 1
+          end
+        end
+        Report.new(events, unreadable, available?(root))
+      rescue StandardError
+        Report.new([], 0, false)
+      end
+
+      def parse(line)
+        value = JSON.parse(line)
+        value.is_a?(Hash) ? value : nil
+      rescue JSON::ParserError
+        nil
+      end
+
+      # Writable, and never marked. An unwritable scratch directory has
+      # recorded nothing and cannot say so in a marker either, so it is asked
+      # directly rather than inferred from an empty log.
+      def available?(root)
+        return false if File.exist?(marker_path(root))
+
+        dir = File.join(scratch_root(root), SCRATCH)
+        return File.writable?(dir) if File.directory?(dir)
+        # Something is there and it is not a directory, so `mkdir_p` will raise
+        # every time and the marker cannot be written either — which is the
+        # case that proves the marker alone is not enough to answer this.
+        return false if File.exist?(dir)
+
+        File.writable?(scratch_root(root))
+      rescue StandardError
+        false
+      end
+
+      # The good path must not count as friction, or the recorder reports the
+      # verbs being used as evidence that they are not.
+      #
+      # Anchored to the START of the segment, because the question is "is this
+      # an invocation of the gem?" and not "is the gem mentioned?". Matched
+      # anywhere, a board line's own TEXT excused the hand-write that appended
+      # it — `echo "- see okf pro docs" >> .okf/board.md` was never recorded,
+      # and board lines routinely name these verbs. `ShellGuard.own_write?`
+      # does the splitting; this is asked of one segment.
+      #
+      # An assignment prefix is part of the invocation and not a command of its
+      # own, so it is skipped rather than breaking the anchor: `$OKF_HOME` is a
+      # variable this ecosystem actually uses, and `OKF_HOME=/tmp okf pro
+      # snapshot >> .okf/log.md` is the prescribed move with a prefix on it.
+      #
+      # So is a wrapper, and the list is short and named rather than open:
+      # `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. An open rule would be a way
+      # back to matching a mention.
+      WRAPPERS = /(?:bundle\s+exec|env|time|nice|nohup|sudo|command)\s+/.freeze
+      OWN_COMMAND = /\A\s*(?:[A-Za-z_]\w*=\S*\s+)*(?:#{WRAPPERS})*okf\s+pro\b/.freeze
+
+      def own_command?(command)
+        command.to_s.match?(OWN_COMMAND)
+      end
+
+      # The board, and ONLY the board.
+      #
+      # The obvious wider list — board, log, journal day — was wrong in the
+      # direction that destroys the measurement: it counted the PRESCRIBED path
+      # as friction. `snapshot` deliberately has no `--write`, 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 to write. Recording either inflates the banner's request and
+      # points the maintainer at verbs that already exist and already declined
+      # to do that job — which is the same mistake `own_command?` exists to
+      # prevent, made one layer up.
+      #
+      # An Edit to a concept body is judgment and always will be. What is left
+      # is `board.md`: a shape with exactly one correct form, edited by hand
+      # while three verbs cover it.
+      # The path is bundle-relative, so this is an equality rather than a
+      # basename test: `projects/x/board.md` is somebody's notes, not the one
+      # page Rule 3 counts, and the verbs do not touch it.
+      #
+      # One covered path also means the class a row records as IS the path, so
+      # the call site passes it straight through. The `classify` that used to
+      # fold three paths into three classes had two answers nothing could reach
+      # from this door, and a unit test calling it directly kept them green.
+      def covered_path?(rel)
+        rel.to_s == "board.md"
+      end
+
+      # The two answers `covered_by` can give, as constants — so a reader may be
+      # COMPARED against one instead of pattern-matched. `verb_covered?` below
+      # asks a narrower question than `covered_by` answers, and a prefix test on
+      # the prose would have coupled it to wording nobody would think to
+      # preserve.
+      SHELL_ANSWER = "Edit or Write — the trust guards read a tool event, and a shell redirect is none"
+      BOARD_ANSWER = "okf pro capture / promote / demote"
+
+      # What a recorded row maps to, where something already covers it — so the
+      # report says "this is a verb now" rather than making the reader guess,
+      # and phase 3's question keeps being answered after phase 3.
+      #
+      # Keyed on `via` as well as `what`, because the two doors mean different
+      # things about the same file. An Edit to the board is a verb's job. A
+      # SHELL write is a bypass whatever it touched — the trust guards read a
+      # tool event and a redirect produces none — so what covers it is Edit or
+      # Write, not an `okf pro` verb.
+      def covered_by(via, what)
+        return SHELL_ANSWER if via == "shell"
+        return BOARD_ANSWER if what == "board.md"
+
+        nil
+      end
+
+      # Whether an `okf pro` VERB covers it — which is not the same question as
+      # whether anything does. A shell redirect at the board is covered, by Edit
+      # or Write, and there is no verb to ask for; a banner counting it told the
+      # adopter a verb could have done something no verb does.
+      def verb_covered?(via, what)
+        answer = covered_by(via, what)
+        !answer.nil? && answer != SHELL_ANSWER
+      end
+
+      # Everything the log holds, cleared — the log itself and the marker.
+      #
+      # The marker is deliberately sticky: one failed write means the count is
+      # short by an unknown amount forever after, and a recorder that quietly
+      # forgave itself would be back to reporting a zero it did not count. But
+      # sticky with no way out is a report that nags permanently about a full
+      # disk from three weeks ago, so the way out is explicit, named in the
+      # message, and belongs to the reader.
+      def clear(root)
+        [ log_path(root), marker_path(root) ].count do |path|
+          next false unless File.exist?(path)
+
+          File.unlink(path)
+          true
+        end
+      rescue StandardError
+        nil
+      end
+
+      # The covered classes, read out of a shell COMMAND instead of a path. A
+      # command has no `file_path` — that is the whole reason `shell-guard`
+      # exists — so this reads the names it mentions, and answers "unclassified"
+      # when it cannot tell. That is not a failure: the report's question is which
+      # verb is missing, and a write it cannot attribute is exactly the row that
+      # says "we do not know yet".
+      #
+      # Wider than `covered_path?`, deliberately, and the two doors are asking
+      # different questions: the edit door asks "is this a shape a verb covers?",
+      # and a redirect is a bypass whatever it touched. `journal` collapses a year
+      # of days into one row rather than three hundred.
+      def classify_command(command)
+        text = command.to_s
+        return "board.md" if text.include?("board.md")
+        return "log.md" if text.include?("log.md")
+        return "journal" if text.match?(%r{journal/\d{4}-\d{2}-\d{2}\.md})
+
+        "unclassified"
+      end
+    end
+  end
+end

data/lib/okf/pro/guards.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+module OKF
+  module Pro
+    # The trust rules. Both are PreToolUse, so they deny the write rather than
+    # complain after it, and both scope through Target first: `verified:` and
+    # the journal calendar are bundle vocabulary, and a guard that fired on
+    # them anywhere — the README quoting the frontmatter format, a scratch
+    # file under .tmp/ — was a false block that trains people to switch the
+    # guard off.
+    module Guards
+      # The block-style spelling, and the fast path. It is NOT the whole
+      # rule: YAML frontmatter may be a flow mapping — `{type: Briefing,
+      # verified: 2026-08-01}` — which the okf reader parses as a real
+      # attestation and this pattern never sees. A gate that reads a
+      # narrower grammar than the parser it defends is a gate with a door
+      # cut into it, so the flow spelling gets its own pattern below.
+      # Patterns rather than a YAML parse, because the added text of an
+      # Edit is a FRAGMENT — it need not be valid YAML, or even contain
+      # the fences — and a parser that failed on a fragment would decline
+      # to see the very attestation it was called to catch.
+      ATTESTATION = /^[[:blank:]]*verified[[:blank:]]*:/.freeze
+
+      # `verified` as a key ANYWHERE in a flow mapping — after `{`, after a
+      # comma, at any nesting. Matched against the added text only when it
+      # actually contains a flow mapping, so prose that happens to say
+      # "verified:" in a sentence does not trip it.
+      FLOW_ATTESTATION = /[{,][[:blank:]]*['"]?verified['"]?[[:blank:]]*:/.freeze
+
+      JOURNAL_ENTRY = %r{\Ajournal/(\d{4}-\d{2}-\d{2})\.md\z}.freeze
+
+      module_function
+
+      # Every spelling of the attestation the okf reader would accept. The
+      # test is deliberately generous: this gate ASKS, so a false positive
+      # costs one prompt and a miss costs a forged signature.
+      def attests?(text)
+        text = text.to_s
+        ATTESTATION.match?(text) || FLOW_ATTESTATION.match?(text)
+      end
+
+      # `verified:` is the owner's signature, and an agent that can type it
+      # unchecked can forge it. Everything downstream — the To-read line, the
+      # briefing's standing, the audit — rests on that block meaning a person
+      # actually read the source. This is the most load-bearing gate in the repo.
+      #
+      # It asks rather than denies, because the invariant was never who holds
+      # the pen — it is who decided. The owner reviews with the agent and the
+      # agent promotes the change; this gate turns that write into an explicit
+      # owner approval, and the approval IS the attestation. Where nobody can
+      # approve — an unattended session — "ask" has no approver and the write
+      # is refused, which is the fail-closed floor the old outright denial had.
+      def guard_verified(event)
+        return [] if Target.for(event).nil?
+        return [] unless attests?(event.added_text)
+
+        { "ask" => "This edit writes 'verified:' — owner attestation. The agent is the scribe; " \
+                   "your approval is the attestation. Approve ONLY if you have actually reviewed " \
+                   "this content yourself. If you have not, deny — unverified is the truth." }
+      end
+
+      # A past day is a record. Editing it does not correct history, it destroys
+      # the one artefact that says what was known at the time — that stays a
+      # flat refusal. Creating a missing past day is different, and it is the
+      # owner's call, not the agent's: Rule 2's fallback is reconstructing
+      # yesterday's missing entry, declared as reconstructed — but "the file
+      # does not exist" alone would let an agent fabricate any date in the
+      # past as quietly as filing a note, and the same guard would then defend
+      # the forgery as history. So creation asks, exactly like `verified:`:
+      # interactive, the owner approves the reconstruction; unattended, no
+      # approver, fail closed.
+      def journal_guard(event, today: Date.today)
+        target = Target.for(event)
+        return [] if target.nil?
+
+        match = target.rel.match(JOURNAL_ENTRY)
+        return [] unless match
+        return [] unless match[1] < today.to_s
+
+        unless target.exist?(target.rel)
+          return { "ask" => "This creates journal/#{match[1]}.md — a PAST day that has no entry. " \
+                            "Approve ONLY if this is a declared reconstruction of a day you " \
+                            "actually worked (Rule 2's fallback). A fabricated record is worse " \
+                            "than a gap: this guard will defend whatever you approve as history." }
+        end
+
+        [ "BLOCKED — journal/#{match[1]}.md is a past day. Records are append-only; " \
+          "corrections go in today's entry, pointing back." ]
+      end
+    end
+  end
+end

data/lib/okf/pro/log/edit.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module OKF
+  module Pro
+    module Log
+      # log.md's one text transform — a dated line, appended under its day.
+      #
+      # The counterpart of Board::Edit, and separate from it for the reason
+      # `Log` is separate from `Board`: the log's newest-first convention is a
+      # rule of this file alone, and it is the rule every earlier defect here
+      # turned on — the audit interrogating the oldest day, the banner printing
+      # day one's counters forever. A new day's heading therefore goes at the
+      # TOP of the day sequence, not at the end of the file.
+      #
+      # Returns `[text, added]`, where `added` is the exact list of lines
+      # spliced in — the caller's claim to `Conserve`, blank lines included,
+      # because a blank line is a line and a guard that ignored them could be
+      # walked past with one.
+      module Edit
+        module_function
+
+        def add_entry(text, day, line)
+          lines = Pro.newline_terminated(text).lines
+          heading = "## #{day}"
+          at = lines.index { |l| l.start_with?("## ") && l.chomp.rstrip == heading }
+          at ? into_existing_day(lines, at, line) : as_a_new_day(lines, heading, line)
+        end
+
+        # After the day's last non-blank line, so the entry joins the day
+        # rather than floating below it — and before whatever blank line
+        # separates this day from the next.
+        def into_existing_day(lines, at, line)
+          index = at + 1
+          last = at + 1
+          while index < lines.size
+            break if lines[index].start_with?("## ")
+
+            last = index + 1 unless lines[index].strip.empty?
+            index += 1
+          end
+          added = [ "#{line}\n" ]
+          lines.insert(last, *added)
+          [ lines.join, added ]
+        end
+
+        # Before the first existing day, which in a newest-first log is where
+        # a newer day belongs. With no day at all yet, at the end — a brand-new
+        # bundle ships an undated log whose whole body is its own preamble.
+        def as_a_new_day(lines, heading, line)
+          first = lines.index { |l| l.start_with?("## ") }
+          if first
+            added = [ "#{heading}\n", "\n", "#{line}\n", "\n" ]
+            lines.insert(first, *added)
+          else
+            # The separator counts. It is a line the file did not have, and a
+            # guard that let an unstated blank through is a guard an edit can
+            # be walked past one blank at a time.
+            added = []
+            added << "\n" unless lines.empty? || lines.last.strip.empty?
+            added.push("#{heading}\n", "\n", "#{line}\n")
+            lines.concat(added)
+          end
+          [ lines.join, added ]
+        end
+      end
+    end
+  end
+end

data/lib/okf/pro/log.rb

@@ -0,0 +1,162 @@
+# frozen_string_literal: true
+
+module OKF
+  module Pro
+    # log.md as data. Pure, for the same reason Board is.
+    module Log
+      module_function
+
+      # The shape of the line Rule 2 appends: a list bullet, then the word,
+      # then its colon — bolding optional, spacing free. Substring matching
+      # ("any line containing Snapshot") was a hole in both directions: a
+      # prose bullet like "- Rewrote the Snapshot checker" under today's
+      # heading posed as the day's snapshot, so the stop gate skipped its
+      # accurate missing-line refusal and reported twelve bogus
+      # disagreements instead — and the audit passed CI on a mention with
+      # no real snapshot anywhere.
+      SNAPSHOT_LINE = /\A[[:blank:]]*[*+-][[:blank:]]+\*{0,2}Snapshot\*{0,2}[[:blank:]]*:/.freeze
+
+      # Under *that* day's heading and no further. The shell version set its flag
+      # at the day heading and never cleared it, so yesterday's snapshot
+      # satisfied today — which is exactly the check being asked for.
+      def snapshot_under?(text, day)
+        !snapshot_line(text, day).nil?
+      end
+
+      # The one walk over the log's day blocks — every public reader below
+      # consumes it, so the heading rule, the calendar rule, and the
+      # last-line-wins rule cannot drift apart again (they did, twice: a
+      # hand-rolled heading compare beside DAY_HEADING, then a calendar
+      # check present in one loop and absent from the other). Yields
+      # [day, line] per block in file order: day is the heading's captured,
+      # calendar-valid date; line is the LAST snapshot line within that
+      # block — a corrected line is appended rather than history rewritten,
+      # and the last word is the current one — or nil when the block has
+      # none.
+      def each_day_block(text)
+        day = nil
+        line = nil
+        text.to_s.each_line do |l|
+          if l.start_with?("## ")
+            yield [ day, line ] if day
+            day = accepted_day(l)
+            line = nil
+            next
+          end
+          line = l if day && l.match?(SNAPSHOT_LINE)
+        end
+        yield [ day, line ] if day
+      end
+
+      # The heading acceptance rule, ONCE: the captured date when the line
+      # is a calendar-valid day heading, else nil. Both walks — the block
+      # iterator above and the audit's partition below — call this, so a
+      # tolerance change cannot land in one and leave the other silently
+      # disagreeing about which days exist.
+      def accepted_day(line)
+        match = line.match(DAY_HEADING)
+        match && Board.parse_date(match[1]) ? match[1] : nil
+      end
+
+      # The day's Snapshot line. The same date can head two blocks — two
+      # sessions in one day, or a merge — and every block counts, but the
+      # file runs newest-first, so the FIRST block holding a snapshot wins:
+      # taking the last block in file order handed the stale bottom copy to
+      # the very gate that verifies counters against the board.
+      def snapshot_line(text, day)
+        each_day_block(text) do |d, line|
+          return line if line && d == day.to_s
+        end
+        nil
+      end
+
+      # The full shape, anchored at both ends: unanchored, `## 2026-08-123`
+      # captured a valid-looking date out of a typo and adopted the block,
+      # while `## 2026-8-12` (missing zero-pad) matched nothing and fell
+      # out of BOTH buckets — neither checked nor reported.
+      DAY_HEADING = /^## (\d{4}-\d{2}-\d{2})[[:blank:]\r]*$/.freeze
+
+      # What counts as an ATTEMPT at a day heading: `## ` then a digit.
+      # "## Notes" is a legal non-day heading; "## 2026-8-12" is a day
+      # heading gone wrong, and the difference is what keeps malformed_days
+      # from flagging prose while still catching every typo class.
+      DAYISH_HEADING = /^## [[:blank:]]*\d/.freeze
+
+      # One scan, one partition: every heading that attempts a date lands in
+      # exactly one bucket, so a rule change cannot open a gap where a
+      # heading is neither checked nor reported. days() is the calendar's
+      # accepted list — a typo'd `## 2026-08-32` string-sorts above every
+      # real date, and unvalidated it became the "newest day" the audit
+      # interrogated while the genuine newest day carried none.
+      def day_partition(text)
+        good = []
+        bad = []
+        text.to_s.each_line do |line|
+          next unless line.match?(DAYISH_HEADING)
+
+          day = accepted_day(line)
+          if day
+            good << day
+          else
+            bad << line.chomp.rstrip.sub(/\A## /, "")
+          end
+        end
+        [ good, bad ]
+      end
+
+      def days(text)
+        day_partition(text)[0]
+      end
+
+      # The headings days() refused, for the audit to say out loud — a
+      # heading no check will ever look under must not rot in silence.
+      def malformed_days(text)
+        day_partition(text)[1]
+      end
+
+      # The maximum date, not the first heading. The file's own convention is
+      # newest-first, but prose is the only thing that ever said so — an entry
+      # appended at the bottom made the audit interrogate the *oldest* day,
+      # which had its snapshot, and CI passed while the real newest day had
+      # none. What CI asks about is the newest day rather than today, because
+      # a push can land on a day nobody worked and a gate that fails on the
+      # calendar is a gate people learn to ignore.
+      def newest_day(text)
+        days(text).max
+      end
+
+      # The most recent snapshot in the file, by date, WITH the day it was found
+      # under. The session banner and `okf pro state` both label the parsed
+      # counters "as of" that day rather than as live, and a label re-derived
+      # by a second scan would be a second chance to disagree with the line it
+      # labels. (A line-only sibling stood here until `state` became the one
+      # source both surfaces read; it was a two-line delegation to this, and
+      # only a unit test still called it.)
+      #
+      # By DATE, not by position. Grepping the whole file and taking the last
+      # hit read the file's *bottom*, which in a newest-first log is the oldest
+      # entry: from day two onward the banner reported the first-ever counters,
+      # inverting the delta it exists to show.
+      #
+      # One pass, O(filesize), because this runs at every session start on a
+      # file that only grows: the composed version cost a full rescan per
+      # candidate day, which was seconds on a years-old log exactly when
+      # discipline had lapsed and the banner mattered most. Two scalars, not
+      # per-day hashes — the strict greater-than keeps the first block of a
+      # repeated day, the newest-first winner, for free, and there is no second
+      # copy of the walk left to drift.
+      def latest_snapshot_entry(text)
+        best_day = nil
+        best_line = nil
+        each_day_block(text) do |day, line|
+          next unless line
+          next unless best_day.nil? || day > best_day
+
+          best_day = day
+          best_line = line
+        end
+        [ best_day, best_line ]
+      end
+    end
+  end
+end