okf-pro 1.0.0

data/lib/okf/pro/pairing.rb

@@ -0,0 +1,271 @@
+# frozen_string_literal: true
+
+module OKF
+  module Pro
+    # The board↔work invariants, in both directions: everything open is on the
+    # board, everything the board links is still real, and everything owed is
+    # still owed. These are what an editor-made commit bypasses entirely, which
+    # is why they are also the CI door's payload.
+    #
+    # Pairing is by link target, never by substring. The first cut asked
+    # `board.include?(slug)`, which a project name mentioned in any unrelated
+    # capture line satisfied — a false pass, in the fail-open direction this
+    # checker exists to close.
+    module Pairing
+      module_function
+
+      # `board:` and `concepts:` let a caller that already paid for the read
+      # hand it over — the audit reads the board and parses the bundle for
+      # its other checks, and a second parse of every concept on the
+      # pre-commit hot path buys nothing.
+      def failures(root, board: nil, concepts: nil)
+        board ||= Pro.read_text(File.join(root, "board.md"))
+        targets = board_targets(board)
+        concepts ||= ::OKF::Bundle::Reader.read(root).concepts
+
+        unpaired_projects(root, targets) +
+          unpaired_briefings(concepts, targets) +
+          broken_targets(root, board) +
+          closed_project_links(root, board) +
+          stale_read_lines(concepts, board)
+      end
+
+      # Forward: every open project is linked from some board line.
+      def unpaired_projects(root, targets)
+        open_projects(root).map do |name|
+          prefix = "/projects/#{name.downcase}"
+          next if targets.any? { |t| t == prefix || t.start_with?("#{prefix}/") }
+
+          "— pairing: projects/#{name} has no board line and no closed marker."
+        end.compact
+      end
+
+      # Forward: every generated-without-verified briefing is linked from some
+      # board line — the To-read line it was born paired with, or the conflict
+      # line that is also a claim on attention.
+      def unpaired_briefings(concepts, targets)
+        unverified_ids(concepts).map do |id|
+          next if targets.include?("/#{id}.md".downcase)
+
+          "— pairing: unverified briefing #{id}.md has no read-owed board line — " \
+            "it silently left the attention system."
+        end.compact
+      end
+
+      # Reverse: every bundle link the board carries lands on something real.
+      # `okf lint` checks links inside concepts, but the board's capture lines
+      # use the bare `[/path]` form lint never parses — rot here is invisible
+      # to everything but this.
+      def broken_targets(root, board)
+        entries = bundle_entries(root)
+        board_lines(board).flat_map do |line|
+          Board.targets(line).map do |target|
+            next if entries.include?(target.downcase.chomp("/"))
+
+            "— pairing: board line links #{target}, which does not exist in the bundle."
+          end.compact
+        end
+      end
+
+      # Reverse: closure removes board lines wholesale, so a line still linking
+      # a closed project is the ritual left half-done.
+      def closed_project_links(root, board)
+        closed = closed_projects(root)
+        return [] if closed.empty?
+
+        board_lines(board).flat_map do |line|
+          Board.targets(line).map do |target|
+            slug = target[%r{\A/projects/([^/\s]+)}i, 1]
+            next unless slug && closed.include?(slug.downcase)
+
+            "— pairing: board line still links projects/#{slug}, which is closed — " \
+              "closure removes its board lines."
+          end.compact
+        end
+      end
+
+      # Reverse: a read-owed line whose briefing is already verified. Reading
+      # is the one event that removes the line, and it happened. A To-read line
+      # with no bundle link at all is fine — documents live outside bundles too,
+      # and the check speaks only about what it can see.
+      def stale_read_lines(concepts, board)
+        verified = verified_reference_targets(concepts)
+        Board.section_lines(board, "To read").flat_map do |line|
+          Board.targets(line).map do |target|
+            next unless verified.include?(target.downcase)
+
+            "— pairing: read-owed line links #{target}, which is already verified — " \
+              "reading removes the line, and the reading happened."
+          end.compact
+        end
+      end
+
+      # Visible lines only — a commented-out sample line must not be a
+      # pairing target or a broken-link finding, for the same reason the
+      # counters do not count it.
+      def board_lines(board)
+        Board.visible(board).each_line.select { |l| l.start_with?("- ") }
+      end
+
+      def board_targets(board)
+        board_lines(board).flat_map { |l| Board.targets(l) }.map(&:downcase)
+      end
+
+      # Downcased so pairing behaves the same on a case-sensitive filesystem
+      # as on the case-insensitive one the bundle was probably written on.
+      def bundle_entries(root)
+        Dir.glob(File.join(root, "**", "*"))
+           .map { |p| "/#{p[(root.size + 1)..-1]}".downcase.chomp("/") }
+      end
+
+      def open_projects(root)
+        project_dirs(root).map do |dir|
+          File.basename(dir) unless closed?(root, File.join(dir, "index.md"))
+        end.compact
+      end
+
+      def closed_projects(root)
+        project_dirs(root).map do |dir|
+          File.basename(dir).downcase if closed?(root, File.join(dir, "index.md"))
+        end.compact
+      end
+
+      def project_dirs(root)
+        Dir.glob(File.join(root, "projects", "*", "")).sort
+      end
+
+      # Closure is one marker, matched as one pattern: the word "closed" —
+      # not hyphen-joined into a name — then its date, with only marker
+      # punctuation between, read across the top of the index (three lines,
+      # the old tolerance), never the body. Every weaker reading failed in
+      # practice: bare /closed/i made titles and verbs into closures;
+      # word-plus-date-anywhere closed dated titles; a forty-character gap
+      # admitted prose; whitelisting "on" re-admitted "The office closed on
+      # 2026-01-05"; and an unguarded comma admitted "we closed, 2026-01-05,
+      # the books". The accepted spellings are enumerated ONCE, in the
+      # skill's closing ritual; MARKER is that enumeration, and the grammar
+      # tests pin both lists to each other.
+      MARKER = /\bclosed\b(?!-)[[:blank:]*(\u2014\u2013:-]*\d{4}-\d{2}-\d{2}/i.freeze
+
+      # A negation must not close the thing it denies. This is a blacklist
+      # of negators, and honestly so — a two-literal lookbehind briefly
+      # posed as "not negated" while "**not** closed", a double space, or
+      # "wasn't" walked straight past it. Markup and punctuation may sit
+      # between the negator and the verb, exactly as they may sit between
+      # the verb and its date.
+      NEGATED = /\b(?:not|never|no longer|isn['\u2019]?t|wasn['\u2019]?t|hasn['\u2019]?t)[\W_]*closed\b/i.freeze
+
+      def marker?(line)
+        line.match?(MARKER) && !line.match?(NEGATED)
+      end
+
+      # Read through the kernel's containment primitive rather than File.read:
+      # this holds a root, and `SafeRead.read!` resolves the path and refuses
+      # one whose symlinks escape it. Byte-identical output for every real
+      # file — the `.scrub` is still this gem's, because `read!` tags the
+      # encoding without validating it and one invalid byte anywhere raises out
+      # of the first regex, which the hook protocol reads as non-blocking.
+      #
+      # NOT applied at `BundleRoot.root_index?`, which has no root to contain
+      # against — it is deciding what the root is — and where a raise would be a
+      # permanent lockout and a rescue would answer "not a root", mis-rooting
+      # the bundle and disarming the journal guard.
+      # Contained against the BUNDLE root, which every caller already holds.
+      # Deriving it as `dirname(dirname(index_path))` gave `<bundle>/projects`,
+      # so `SafeRead` refused any project index whose realpath left `projects/`
+      # — including one that never leaves the bundle. A project legitimately
+      # archived behind a symlink (`projects/beta -> ../archive/beta`) read as
+      # open forever, and the audit demanded a board line for work closed
+      # months ago. The containment rule is about the bundle, and a root
+      # invented from the path being checked is not the bundle.
+      def closed?(root, index_path)
+        return false unless File.exist?(index_path)
+
+        Pro.read_contained(root, index_path).lines.first(3).any? { |line| marker?(line) }
+      rescue ::OKF::Path::Error, ::Errno::ENOENT
+        # A project index reached only through a symlink out of the bundle is
+        # not a closure marker anyone may rely on. Open is the safe answer: an
+        # open project keeps its board line, a closed one loses it.
+        false
+      end
+
+      # ── the read-owed rule, in the kernel's vocabulary ─────────────────────
+      #
+      # These two are exact opposites and MUST stay so, or a briefing falls
+      # through both: `unverified_ids` says "the board still owes this a To-read
+      # line", `verified_reference_targets` says "the line can go". They are
+      # read by `unpaired_briefings` and `stale_read_lines` respectively, plus
+      # `Attestation.report` and the snapshot counter — four call sites, one
+      # rule, and the rule is:
+      #
+      #   a briefing is owed a read until a HUMAN has verified it.
+      #
+      # `okf` 2.0 answers that directly. `declared_generated?` is raw-key
+      # detection, so it distinguishes hand-written (no provenance at all) from
+      # v0.1-with-a-timestamp, which the old `frontmatter["generated"]` test
+      # conflated with the fallback. And `trust_tier` reads §5.3: no `verified`
+      # is unverified, a `process:` or agent actor is machine-confirmed, a
+      # `human:<id>` actor is human-reviewed.
+      #
+      # The tier is what makes these opposites rather than merely different.
+      # Testing `frontmatter["verified"]` for truthiness made a nightly
+      # `process:`-verified briefing simultaneously *awaiting the owner's read*
+      # to one caller and *verified, drop the line* to the other — the board
+      # line vanished and the read was never owed to anyone again. Moving one
+      # site and not the other manufactures exactly that state, which is why
+      # this comment sits over both of them.
+      def awaiting_read?(concept)
+        concept.declared_generated? && concept.trust_tier != :human_reviewed
+      end
+
+      def owner_read?(concept)
+        concept.trust_tier == :human_reviewed
+      end
+
+      def briefing?(concept)
+        concept.id.start_with?("reference/")
+      end
+
+      def unverified_ids(concepts)
+        concepts.map do |concept|
+          next unless briefing?(concept)
+          next unless awaiting_read?(concept)
+
+          concept.id
+        end.compact
+      end
+
+      def verified_reference_targets(concepts)
+        concepts.map do |concept|
+          next unless briefing?(concept)
+          next unless owner_read?(concept)
+
+          "/#{concept.id}.md".downcase
+        end.compact
+      end
+
+      # The one shell-out in the whole checker. `--` plus the pathspec keeps it
+      # to markdown, so a change confined to hooks or CI does not summon Rule 2's
+      # end-of-day questions.
+      def dirty_markdown?(root)
+        out = IO.popen(
+          [ "git", "-C", root, "status", "--porcelain", "--", "*.md" ],
+          err: File::NULL, &:read
+        )
+        # Only a git that ran and answered may disengage the gate. A git that
+        # failed — dubious ownership, a corrupted .git, a root outside any
+        # repository — is not "no work happened"; it is "nobody can tell",
+        # and a gate that cannot tell must not wave the session through.
+        # Returning false here was the silent-disarm hole: stderr was nulled,
+        # the empty read looked clean, and the stop gate asked no questions.
+        return true unless $?.success?
+
+        !out.to_s.strip.empty?
+      rescue Errno::ENOENT
+        # No git at all is the same state as a failing one — nobody can tell
+        # whether work happened — and gets the same answer.
+        true
+      end
+    end
+  end
+end

data/lib/okf/pro/reconcile.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+module OKF
+  module Pro
+    # Rule 1 — writing is reconciliation.
+    #
+    # Fires on Write, not Edit: a new concept is the moment a claim enters the
+    # corpus, and the moment both it and whatever it collides with are cheapest
+    # to hold in one head. Its reach is bounded by the filename's vocabulary,
+    # which is exactly the limit the rule states about itself — it catches
+    # collisions as well as your search words do, and no better.
+    module Reconcile
+      module_function
+
+      def search(target, event)
+        return [] if target.nil?
+        return [] unless event.tool_name == "Write"
+        return [] if target.rel.start_with?("journal/")
+        return [] if NO_RECONCILE.include?(target.basename)
+
+        hits = terms(target).map { |term| block_for(target, term) }.compact
+        return [] if hits.empty?
+
+        [ "RULE 1 — reconciliation. Existing concepts share this new concept's vocabulary. " \
+          "Read them now: contradiction, supersession, or duplicate? Deprecate the loser at this " \
+          "moment, or file a conflict line on board.md. Do not simply continue.\n#{hits.join("\n")}" ]
+      end
+
+      def terms(target)
+        File.basename(target.rel, ".md").split("-")
+            .reject { |t| t.empty? || STOP_WORDS.include?(t.downcase) }
+            .first(4)
+      end
+
+      def block_for(target, term)
+        rows = matches(target, term)
+        return nil if rows.empty?
+
+        statuses = status_index(target.bundle)
+        body = rows.map do |r|
+          "    #{r[:id]}#{settled(statuses[r[:id]])}  ·  #{r[:type]}  ·  #{r[:title]}\n      #{r[:snippet]}"
+        end
+        "— '#{term}':\n#{body.join("\n")}"
+      end
+
+      # §5.4's `status`, made operative. The skill teaches `status: deprecated`
+      # as the machine-readable half of Rule 1's supersession move — correct the
+      # loser NOW, and mark it — and this is what makes that teaching worth
+      # anything: a collision with a concept that has already been deprecated is
+      # a collision somebody already settled, and re-litigating it is the cost
+      # the marking exists to avoid.
+      #
+      # It annotates rather than filters. A deprecated concept is "kept for
+      # links and history, no longer current" (§5.4), so it is still a real hit
+      # and still worth reading — what changes is what the reader does about it.
+      # Filtering it out would hide the evidence that the question was answered.
+      def settled(status)
+        status == "deprecated" ? "  [deprecated — this collision was already settled]" : ""
+      end
+
+      def status_index(bundle)
+        bundle.concepts.each_with_object({}) { |concept, index| index[concept.id] = concept.status }
+      end
+
+      # The concept being written is excluded (it is not its own collision), and
+      # so are the structural files: a hit in README or board.md means they quote
+      # a concept, not that they assert against one.
+      def matches(target, term)
+        ::OKF::Bundle::Search.call(target.bundle, term)
+                             .reject { |r| r[:id] == target.id }
+                             .reject { |r| NO_RECONCILE.include?("#{File.basename(r[:id])}.md") }
+                             .first(5)
+      end
+    end
+  end
+end

data/lib/okf/pro/records.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+module OKF
+  module Pro
+    # The append-only record, checked against git rather than against a tool
+    # event.
+    #
+    # `Guards.journal_guard` refuses an edit to a past day at the agent's
+    # tool boundary, which is the right place to catch it and the wrong place
+    # to rely on: it reads a PreToolUse event, so it sees Edit and Write and
+    # nothing else. A shell redirect, an editor, a patch — none of them
+    # produce the event, and the record they rewrite is exactly the artefact
+    # nobody can reconstruct afterwards.
+    #
+    # This asks the same question of the index, where the answer does not
+    # depend on which tool made the change: does this commit modify or delete
+    # a journal day that already exists in HEAD, and is that day in the past?
+    # Only additions and today's entry survive. It runs at the commit door,
+    # which every path to history goes through.
+    module Records
+      JOURNAL_ENTRY = %r{journal/(\d{4}-\d{2}-\d{2})\.md\z}.freeze
+
+      module_function
+
+      # Findings, or []. `root` is the repository — this reads the index, not
+      # a materialised tree, because the question is about a change rather
+      # than a state.
+      def staged_violations(root, today: Date.today)
+        status = staged_status(root)
+        return status[:findings] unless status[:findings].empty?
+
+        status[:entries].map do |mode, path|
+          match = path.match(JOURNAL_ENTRY)
+          next unless match
+
+          day = match[1]
+          next unless day < today.to_s
+
+          verb = VERBS.fetch(mode[0, 1], "modifies")
+          "  records  this commit #{verb} #{path}, a past day that already exists in HEAD. " \
+            "Records are append-only; corrections go in today's entry, pointing back."
+        end.compact
+      end
+
+      # What the status letter did to the day, in the words a refusal needs. A
+      # typechange is its own verb because it is its own act: the day's content
+      # is not edited, it is replaced wholesale by a link somewhere else.
+      VERBS = { "D" => "deletes", "T" => "replaces" }.freeze
+
+      # Modified, deleted, renamed and TYPECHANGED paths in the index, against
+      # HEAD. Additions are absent by construction — a day being written for
+      # the first time is the reconstruction the journal guard already routes
+      # to the owner, and this door does not second-guess an approval it cannot
+      # see.
+      #
+      # `T` was absent and is the worst omission of the four: replacing a
+      # committed past day with a symlink stages as a typechange, never as `M`
+      # or `D`, so the gate reported "append-only" and the commit destroyed the
+      # one artefact this module exists to protect. The filter is a whitelist,
+      # so every letter it does not name fails OPEN — which is why it is named
+      # here with its reason rather than left to be re-derived.
+      def staged_status(root)
+        out = IO.popen(
+          [ "git", "-C", root, "diff", "--cached", "--name-status", "--diff-filter=MDRT" ],
+          err: File::NULL, &:read
+        )
+        # A git that could not answer is not an empty answer. The commit door
+        # refuses what it cannot check, exactly as dirty_markdown? does.
+        unless $?.success?
+          return { findings: [ "  records  git could not report the staged changes, so the " \
+                               "append-only record could not be checked. The commit is refused " \
+                               "rather than waved through." ], entries: [] }
+        end
+
+        entries = out.to_s.each_line.map do |line|
+          mode, *paths = line.strip.split("\t")
+          next if mode.nil? || paths.empty?
+
+          # A rename reports source and destination; the source is the one
+          # leaving its place.
+          [ mode, paths.first ]
+        end.compact
+        { findings: [], entries: entries }
+      rescue Errno::ENOENT
+        { findings: [ "  records  git is not available, so the append-only record could not be " \
+                      "checked. The commit is refused rather than waved through." ], entries: [] }
+      end
+    end
+  end
+end