okf-pro 1.0.0

data/lib/okf/pro/audit.rb

@@ -0,0 +1,161 @@
+# frozen_string_literal: true
+
+module OKF
+  module Pro
+    # The CI door: the same invariants the hooks enforce, minus the ones that
+    # need a tool event.
+    #
+    # It exists because hooks fire only at the agent's tool boundary — an edit
+    # made in a text editor reaches the repo unchecked. The snapshot check asks
+    # whether the *newest* day in the log carries one, not today's: CI runs on a
+    # push, which can land on a day nobody worked, and a gate that fails on the
+    # calendar teaches people to ignore it.
+    module Audit
+      module_function
+
+      # Takes a repository root or a bundle root; both resolve. CI runs it as
+      # `okf pro audit .` from the top of the checkout, which is neither
+      # more nor less correct than naming `.okf` — the caller should not have
+      # to know the layout to ask whether the bundle is sound.
+      def call(start)
+        root = BundleRoot.resolve(start)
+        if root.nil?
+          return [ "#{File.expand_path(start.to_s)} holds no OKF bundle — no index.md, and none in .okf/." ]
+        end
+
+        bundle = ::OKF::Bundle::Reader.read(root)
+        findings = ambiguous_layout(start, root).map { |m| "  layout    #{m}" } +
+                   structure(root).map { |m| "  structure #{m}" } +
+                   conformance(bundle) + curation(bundle) + snapshot(root)
+        # Budget and pairing read the board; with the board gone the structure
+        # finding is the whole story, and a crash would bury it. The board is
+        # read once and the bundle parsed once, here — Rule 3 goes through
+        # Budget.check_text (the same code the cap-check hook runs, so the
+        # doors cannot drift apart), and pairing reuses both reads.
+        board_path = File.join(root, "board.md")
+        if File.exist?(board_path)
+          board = Pro.read_text(board_path)
+          findings += Budget.check_text(board).map { |m| "  budget    #{m}" }
+          findings += Board.grammar(board).map { |m| "  board     #{m}" }
+          findings += pairing(root, board: board, concepts: bundle.concepts)
+        end
+        findings
+      end
+
+      # Two bundles in one directory — a flat root that also parents an
+      # `.okf` root. The doors disagree there by construction: the trust
+      # guards govern a file outside `.okf` by the flat root (a root that
+      # does not contain the file is no root of it), while this audit and
+      # the stop gate govern `.okf`. Neither choice is wrong; the LAYOUT
+      # is, and a disagreement nobody is told about is the silent failure
+      # the contract forbids. Mid-migration is the honest case, and the
+      # answer is the same: finish the move.
+      def ambiguous_layout(start, root)
+        base = File.expand_path(start.to_s)
+        return [] unless root == File.join(base, BundleRoot::DIR)
+        return [] if BundleRoot.root_kind(base).nil?
+
+        [ "#{base} is a bundle AND holds a bundle at #{BundleRoot::DIR}/ — two roots, one " \
+          "directory. Files outside #{BundleRoot::DIR}/ are guarded against the outer one and " \
+          "audited against the inner: the doors disagree until one of the two is retired." ]
+      end
+
+      # The closed core. `okf validate` knows nothing of these — they are the
+      # method's skeleton, not the format's — and a bundle missing one is not a
+      # leaner bundle, it is a broken one: without them the gates disengage in
+      # silence, which is the one failure the contract forbids. roadmap.md is
+      # deliberately absent from this list — it is the one file the design lets
+      # an adopter delete, by its own standing accusation.
+      CORE = [
+        [ "board.md",        "the one page of state" ],
+        [ "log.md",          "delta memory, where the snapshot lands" ],
+        [ "journal/",        "the backward record" ],
+        [ "areas/corpus.md", "the standard this corpus is kept at" ]
+      ].freeze
+
+      def structure(root)
+        CORE.map do |rel, why|
+          path = File.join(root, rel)
+          present = rel.end_with?("/") ? File.directory?(path) : File.file?(path)
+          next if present
+
+          "#{rel} is missing — #{why}. The core is closed; only roadmap.md is deletable."
+        end.compact
+      end
+
+      # Errors AND warnings. Returning early on `valid?` dropped every soft
+      # finding the validator made — and `Conformance`, the hook door, reports
+      # them (`warn_lines`) for a reason it states at length: a scalar
+      # `verified: human:rod` is conformant, so the attestation guard asks, the
+      # owner approves, and the reader then drops the malformed value while the
+      # trust tier stays `unverified` forever. Caught at the agent's tool
+      # boundary and waved through here, which is the door an edit made in an
+      # editor takes, and the door `pre-commit` runs.
+      #
+      # A warning is a finding at this door, the same as a linter warning
+      # already is: `curation` below reads `.warnings` and this verb exits 1 on
+      # them. The two channels answering differently about the same bundle was
+      # the inconsistency, not the severity.
+      def conformance(bundle)
+        result = ::OKF::Bundle::Validator.call(bundle)
+        result.errors.map { |e| "  validate  #{e[:path]}: #{e[:message]}" } +
+          result.warnings.map { |w| "  validate  #{w[:path]}: #{w[:message]} (#{w[:check]})" }
+      end
+
+      # The linter, run the way `Conformance` runs it, and for the same reason
+      # stated there at length: a bare `Linter.call(bundle)` cannot run
+      # `expired` (no clock) or `stale` (no cutoff), and reports `healthy?`
+      # anyway. Measured on this door before this line existed:
+      # `skipped_checks: [:expired, :stale]`, and `okf pro audit — clean.` The
+      # hook door supplied the clock and excluded `stale` in source; this one
+      # did neither, so one clause was kept at one door and broken at the other.
+      #
+      # Separate from `curation` so the residue can be asserted directly rather
+      # than inferred from the findings — the check that this check ran.
+      def linted(bundle)
+        ::OKF::Bundle::Linter.call(bundle, today: Date.today, except: [ :stale ])
+      end
+
+      def curation(bundle)
+        report = linted(bundle)
+        report.warnings.map { |w| "  lint      #{w[:path]}: #{w[:message]} (#{w[:check]})" } +
+          confession(report)
+      end
+
+      # The guard on the guard. `stale` is excluded in source with its reason,
+      # so this is empty in normal operation — and stays a live guard for the
+      # day okf adds a third clock-gated check, which would otherwise go
+      # unchecked here in silence.
+      def confession(report)
+        skipped = Array(report.stats[:skipped_checks])
+        return [] if skipped.empty?
+
+        [ "  lint      okf lint could not run #{skipped.join(", ")} on this bundle, so those are " \
+          "unchecked rather than clean." ]
+      end
+
+      def snapshot(root)
+        path = File.join(root, "log.md")
+        return [] unless File.exist?(path)
+
+        text = Pro.read_text(path)
+        # A heading the calendar rejects is a day no check will ever look
+        # under — said here, because days() skipping it in silence is how a
+        # one-digit typo would orphan an entry forever.
+        findings = Log.malformed_days(text).map do |day|
+          "  snapshot  log.md heading '## #{day}' is not a calendar date — nothing will ever check under it."
+        end
+        newest = Log.newest_day(text)
+        unless newest.nil? || Log.snapshot_under?(text, newest)
+          findings << "  snapshot  log.md's newest day (#{newest}) carries no Snapshot line."
+        end
+        findings
+      end
+
+      def pairing(root, board:, concepts:)
+        Pairing.failures(root, board: board, concepts: concepts)
+               .map { |m| "  pairing #{m.sub(/\A— pairing:/, "")}" }
+      end
+    end
+  end
+end

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

@@ -0,0 +1,201 @@
+# frozen_string_literal: true
+
+module OKF
+  module Pro
+    module Board
+      # The board's text transforms — text in, text out, and nothing else.
+      #
+      # Every write verb's whole computation lives here, so that the shell
+      # around it is a read, a conservation check and a rename. That split is
+      # what makes `Conserve` worth having: a transform that also wrote its own
+      # result could satisfy its own guard, and a writer that satisfies its own
+      # gate proves nothing.
+      #
+      # The transforms return `[text, delta]`, where delta is the claim the
+      # caller hands to `Conserve` — never a promise this module keeps by
+      # being careful.
+      module Edit
+        # The budget face, as one line, with the declared count isolated. The
+        # anchoring is `Board.budget`'s, deliberately: a header this cannot
+        # rewrite is a header that one cannot read, and the two disagreeing is
+        # how a promotion leaves the face lying about the section under it.
+        BUDGET_LINE = %r{^(\*{0,2}[Ii]n [Ff]light:\*{0,2}[^\S\n]*)(\d+)([^\S\n]*/)}.freeze
+
+        module_function
+
+        # A dated capture line, in the one shape the Inbox counter reads.
+        def capture_line(text, today)
+          "- #{today} — #{text.to_s.strip}"
+        end
+
+        # Appended after the section's LAST `- ` line, or immediately after the
+        # heading when the section is empty. Not at the end of the block: a
+        # section can carry prose or a stack of comments below its lines, and
+        # an append that landed under those would read as belonging to them.
+        #
+        # Walks the RAW text, not the visible text — a comment stripped here
+        # would be a comment deleted, which is the regeneration this whole
+        # module exists to make impossible. The two agree on what a heading and
+        # a board line are, because a balanced single-line comment starts with
+        # `<`, and so does neither.
+        def append_to_section(text, section, line)
+          lines = Pro.newline_terminated(text).lines
+          at = insert_point(lines, section)
+          return [ nil, "board has no '## #{section}' section to append to" ] if at.nil?
+
+          lines.insert(at, "#{line}\n")
+          [ lines.join, nil ]
+        end
+
+        def insert_point(lines, section)
+          heading = "## #{section}"
+          start = lines.index { |l| l.start_with?("## ") && l.chomp.rstrip == heading }
+          return nil if start.nil?
+
+          at = start + 1
+          last = at
+          index = at
+          while index < lines.size
+            break if lines[index].start_with?("## ")
+
+            last = index + 1 if lines[index].start_with?("- ")
+            index += 1
+          end
+          last
+        end
+
+        # The line, gone, and nothing else. Matched by exact content so a
+        # near-duplicate elsewhere on the board survives; every occurrence is
+        # removed, because a board carrying the same line twice is carrying one
+        # commitment twice and the caller's delta says how many.
+        def remove_line(text, line)
+          wanted = line.to_s.chomp
+          body = Pro.newline_terminated(text)
+          kept = body.lines.reject { |l| l.chomp == wanted }
+          [ kept.join, body.lines.size - kept.size ]
+        end
+
+        # Out of one section and into another, as one transform, so the
+        # intended delta is a MOVE and the guard can hold it to that. Doing it
+        # as a remove and an append would state two deltas that a dropped line
+        # satisfies just as well.
+        def move_line(text, line, to_section)
+          removed, count = remove_line(text, line)
+          return [ nil, no_such_line ] if count.zero?
+
+          append_to_section(removed, to_section, line.to_s.chomp)
+        end
+
+        # The one way a line `okf pro board` just listed can fail to match: the
+        # selectors read the board's VISIBLE text and this walks the raw text,
+        # so a line carrying a trailing `<!-- ... -->` is listed without its
+        # comment and looked up with it still there. Refusing is the right
+        # answer — moving the visible half would drop the comment, and dropping
+        # anything is what `Conserve` exists to prevent — but a message saying
+        # only "not on the board" sends the reader looking for the wrong thing.
+        def no_such_line
+          "that exact line is not on the board. If it carries a trailing " \
+            "`<!-- ... -->` comment, `okf pro board` lists it without the comment and this " \
+            "verb will not move it: take the comment off the line first, or move it by hand."
+        end
+
+        # The declared half of `In flight: k/CAP`. Returns the new text and the
+        # two lines the caller must declare, or nil when the board has lost its
+        # header — which is Rule 3's own refusal and not this module's to fix.
+        def set_declared(text, count)
+          lines = Pro.newline_terminated(text).lines
+          at = lines.index { |l| l.match?(BUDGET_LINE) }
+          return [ nil, nil, nil ] if at.nil?
+
+          old = lines[at]
+          # Block form: a header carrying `\\1` in its trailing prose would
+          # otherwise be read as a backreference by the replacement string.
+          fresh = old.sub(BUDGET_LINE) { "#{Regexp.last_match(1)}#{count}#{Regexp.last_match(3)}" }
+          return [ lines.join, nil, nil ] if fresh == old
+
+          # Spliced by INDEX. The header is found per line, and putting it back
+          # with `String#sub` searched the whole text for that line's characters
+          # — so any earlier line whose tail happened to equal the header
+          # matched first, and the prose was rewritten while the header stayed
+          # stale. `Conserve` caught the mismatch, which made the verb refuse
+          # while naming a line nobody had touched.
+          lines[at] = fresh
+          [ lines.join, old.chomp, fresh.chomp ]
+        end
+
+        # ── selectors ────────────────────────────────────────────────────────
+        #
+        # Keyed, never positional. okf-principles forbids a positional index
+        # for exactly the reason this file exists: agents rewrite, and "the
+        # third line under Backlog" names a different commitment after any edit
+        # anyone makes. A `/projects/<slug>` link is the board's own key; a
+        # substring is the fallback, and both REFUSE on ambiguity rather than
+        # picking — a verb that guesses which commitment you meant is a verb
+        # that moves the wrong one and reports success.
+        # Selectors that identify no single target. An empty one was refused
+        # from the start, because the target pass builds the prefix
+        # `/projects` out of it and selects every project line on the board —
+        # a selector that names nothing selecting everything, in a verb that
+        # then moves it.
+        #
+        # `/` and `/projects` are that same hazard reached by another spelling,
+        # and the guard missed them: both chomp to a prefix that is a proper
+        # ANCESTOR of every linked line, so `start_with?` turns the name into a
+        # wildcard. `select` only refuses on MORE than one match, so with
+        # exactly one linked line in range the verb moved it and reported
+        # success. A directory every project sits under names none of them.
+        NAMES_NOTHING = [ "", "/projects" ].freeze
+
+        def names_nothing?(selector)
+          NAMES_NOTHING.include?(selector.to_s.strip.chomp("/"))
+        end
+
+        def select(rows, selector, sections: nil)
+          return [ nil, no_match(selector, sections) ] if names_nothing?(selector)
+
+          candidates = sections ? rows.select { |r| sections.include?(r.section) } : rows
+          matches = by_target(candidates, selector)
+          matches = by_substring(candidates, selector) if matches.empty?
+
+          return [ nil, no_match(selector, sections) ] if matches.empty?
+          return [ nil, ambiguous(selector, matches) ] if matches.size > 1
+
+          [ matches.first, nil ]
+        end
+
+        # `alpha` and `/projects/alpha` and `/projects/alpha/index.md` all name
+        # the same commitment, because a board line links the project directory
+        # and a concept inside it interchangeably.
+        def by_target(rows, selector)
+          prefix = selector.to_s.start_with?("/") ? selector.to_s : "/projects/#{selector}"
+          prefix = prefix.chomp("/").downcase
+          rows.select do |row|
+            row.targets.any? do |target|
+              t = target.downcase.chomp("/")
+              t == prefix || t.start_with?("#{prefix}/")
+            end
+          end
+        end
+
+        def by_substring(rows, selector)
+          needle = selector.to_s.strip.downcase
+          return [] if needle.empty?
+
+          rows.select { |row| row.text.downcase.include?(needle) }
+        end
+
+        def no_match(selector, sections)
+          where = sections ? " under #{sections.join(" or ")}" : ""
+          "no board line#{where} matches '#{selector}' — neither as a /projects/ link nor as a " \
+            "substring of a line. `okf pro board` lists what is there."
+        end
+
+        def ambiguous(selector, matches)
+          "'#{selector}' matches #{matches.size} board lines, and picking one would move a " \
+            "commitment nobody named:\n#{matches.map { |r| "  [#{r.section}] #{r.text}" }.join("\n")}\n" \
+            "Name the project link, or a substring only one line carries."
+        end
+      end
+    end
+  end
+end

data/lib/okf/pro/board.rb

@@ -0,0 +1,291 @@
+# frozen_string_literal: true
+
+module OKF
+  module Pro
+    # board.md as data. Pure text in, numbers out — no disk, no bundle, so the
+    # counting rules that Rule 3 enforces can be tested without a fixture.
+    module Board
+      Budget = Struct.new(:declared, :cap)
+
+      # Comments, as the BOARD defines them — one line, balanced:
+      # `<!-- ... -->` is stripped wherever it sits, and a longer note is a
+      # stack of single-line comments. Every richer model failed open in a
+      # review round: character-granular regions let a `<!--` in one
+      # capture's prose swallow real lines up to a `-->` in another's; and
+      # line-start regions were position-dependent, so splicing the text
+      # after a closer changed what a second strip saw and the counters
+      # read a different board than the grammar. Balanced-on-one-line is
+      # the shape that survives ALMOST any splice — nested fragments can
+      # still juxtapose into a span no single reading of the source
+      # contains, which is why strip_comments runs to a fixpoint and
+      # confesses when it needed more than one pass. The rule is narrow
+      # enough to be predictable, not narrow enough to be inviolable, and
+      # the difference is a finding rather than a comment's promise.
+      INLINE_COMMENT = /<!--.*?-->/.freeze
+
+      module_function
+
+      # Board text with comments removed — THE definition of "visible", and
+      # every reader consumes it: the counters, the budget face, the date
+      # checks, the stray-bullet pass, pairing's link scan. Comment-awareness
+      # bolted onto one pass split the module against itself: a commented
+      # sample line was invisible to the stray check but counted by the cap
+      # and flagged by the date check that read it anyway.
+      #
+      # The strip runs to a FIXPOINT, so re-stripping visible text is a
+      # no-op by construction rather than by hope — pathological splices
+      # can juxtapose fragments into a new balanced span, and a strip that
+      # stopped after one pass let the second reader see a different board.
+      # Returns [visible, unclosed?, respliced?]: any `<!--` still standing has no
+      # closer on its line — an intended comment gone wrong, and it is NOT
+      # hidden. The caller confesses it, because comment-intended text read
+      # as board content (a stray chase date, a sample capture) must not
+      # drive counters in silence.
+      def strip_comments(text)
+        visible = text.to_s
+        passes = 0
+        loop do
+          stripped = visible.gsub(INLINE_COMMENT, "")
+          break if stripped == visible
+
+          visible = stripped
+          passes += 1
+        end
+        # A second effective pass means the first strip spliced fragments
+        # into a comment no single reading of the source contains — text
+        # was swallowed that the writer never wrapped. Rare and contrived,
+        # but silent was exactly how the docstring's old "splicing cannot
+        # break this" claim failed, so convergence beyond one pass is a
+        # confession, not a curiosity.
+        [ visible, visible.include?("<!--"), passes > 1 ]
+      end
+
+      def visible(text)
+        strip_comments(text)[0]
+      end
+
+      # Lines under a `## <name>` heading, up to the next `## `. The board's
+      # sections are the unit Rule 3 counts, so one reader serves the cap check
+      # and the session banner alike.
+      def section_lines(text, name)
+        visible_section_lines(visible(text), name)
+      end
+
+      # The section walk over text a caller already made visible — grammar()
+      # strips once and shares; the public section_lines strips for everyone
+      # else, and the fixpoint strip makes the double path harmless.
+      def visible_section_lines(visible_text, name)
+        heading = "## #{name}"
+        inside = false
+        visible_text.each_line.with_object([]) do |line, acc|
+          if line.start_with?("## ")
+            # Exact, not a prefix — the same defect log.rb already paid
+            # for: start_with? folded "## In flight — parked" into
+            # "In flight", inflating the count and turning a correct
+            # budget header into a refusal.
+            inside = (line.chomp.rstrip == heading)
+            next
+          end
+          acc << line if inside && line.start_with?("- ")
+        end
+      end
+
+      def count(text, name)
+        section_lines(text, name).size
+      end
+
+      # One row per visible board line, in file order, with everything a
+      # reader would otherwise re-derive by hand: which section it sits under,
+      # the two date shapes the counters read, and its bundle links.
+      #
+      # Section is carried on the row rather than looked up per line, because
+      # "which section is this line in" is the question every board edit asks
+      # first and the one an agent answers today by counting headings in a
+      # `cat`. Pure, like everything else here — the age in days is the
+      # caller's, since it needs a calendar and this module has none.
+      Row = Struct.new(:section, :text, :line_date, :chase_date, :targets)
+
+      def rows(text)
+        section = nil
+        visible(text).each_line.with_object([]) do |line, acc|
+          if line.start_with?("## ")
+            section = line.chomp.rstrip.sub(/\A## /, "")
+            next
+          end
+          next unless section && line.start_with?("- ")
+
+          stripped = line.chomp
+          acc << Row.new(section, stripped, line_date(stripped), chase_date(stripped), targets(stripped))
+        end
+      end
+
+      # The `In flight: k/CAP` header, or nil when the board has lost it. Matched
+      # by its shape rather than by the first line containing the words, so a
+      # sentence mentioning "in flight" elsewhere cannot be mistaken for the
+      # budget face. The whole shape must sit on one line that IS the header:
+      # anchored at line start (a capture line's "- deck in flight: 3/4" is
+      # not the budget), digits and slash on that same line (`\D*` crawled
+      # across newlines and fabricated a cap from the next N/M below; `\s*`
+      # around the slash did the same one token later, reading a date on the
+      # following line as a cap of 2026).
+      def budget(text)
+        match = visible(text).match(%r{^\*{0,2}[Ii]n [Ff]light:\*{0,2}[^\S\n]*(\d+)[^\S\n]*/[^\S\n]*(\d+)})
+        return nil unless match
+
+        Budget.new(match[1].to_i, match[2].to_i)
+      end
+
+      # Every bundle-absolute link target on a line. Two spellings, both real:
+      # the markdown form `[text](/path)` project lines use, and the bare
+      # `[/path]` form capture and conflict lines use — five-second capture
+      # does not stop to type a link twice. Anything not starting with `/` is
+      # not a bundle link and is not this module's business.
+      def targets(line)
+        text = line.to_s
+        markdown = text.scan(%r{\]\((/[^)\s]+)\)}).flatten
+        bare = text.scan(%r{\[(/[^\]\s]+)\](?!\()}).flatten
+        # Fragments are for readers; the file they resolve against has none.
+        # Kept, `/reference/x.md#tiers` failed the existence check against an
+        # entry list that only ever holds `/reference/x.md`.
+        (markdown + bare).map { |t| t.sub(/#.*/, "") }
+      end
+
+      # The leading `- YYYY-MM-DD` date a capture line carries, or nil. A date
+      # the calendar rejects (month 13) is treated as absent rather than
+      # guessed at — these feed counters, and a counter must not invent.
+      def line_date(line)
+        match = line.to_s.match(/\A-\s+(\d{4}-\d{2}-\d{2})/)
+        return nil unless match
+
+        parse_date(match[1])
+      end
+
+      # The `chase YYYY-MM-DD` date on a Waiting line, or nil. The chase date
+      # is the only thing standing between a dependency and a month of drift,
+      # which is why the snapshot counts the ones already past. The word is
+      # boundary-anchored: without it, "purchase 2026-09-01" read as a chase
+      # date, satisfied the grammar check built to demand one, and reported
+      # an overdue chase nobody ever set.
+      def chase_date(line)
+        match = line.to_s.match(/\bchase\s+(\d{4}-\d{2}-\d{2})/)
+        return nil unless match
+
+        parse_date(match[1])
+      end
+
+      def parse_date(text)
+        Date.parse(text)
+      rescue ArgumentError
+        nil
+      end
+
+      # A board line the counters can see starts `- ` at column zero —
+      # section_lines reads exactly that, everywhere. Any other bullet is a
+      # line every counter is blind to, including the cap: `* 2026-08-18 —
+      # file the claim` under Deadlines counted as zero lines, and so did an
+      # in-flight demand behind an indented dash. The counters' own bullet
+      # rule, flagged instead of silently skipped.
+      STRAY_BULLET = /\A(?:[*+][[:blank:]]|[[:blank:]]+[-*+][[:blank:]])/.freeze
+
+      # The counters read three shapes, exactly — a leading `- YYYY-MM-DD` on
+      # Inbox and Deadlines lines, a literal `chase YYYY-MM-DD` on Waiting
+      # lines — and a dated line in any other spelling parses to nil and is
+      # silently compacted out of every count. Silent is the problem:
+      # "- Due Aug 18: filing" made "deadlines within 7d" say 0, the stop
+      # gate agreed with itself, and the deadline landed unclaimed. So the
+      # unreadable line is a finding, raised at the audit and the stop gate,
+      # instead of a zero nobody can distinguish from a quiet board. The
+      # same goes for the bullet itself: a check that only read the lines
+      # the counters read would have inherited their blindness, so the
+      # stray-bullet pass walks the raw section text instead.
+      def grammar(text)
+        visible_text, unclosed, respliced = strip_comments(text)
+        findings = []
+        if unclosed
+          findings << "a '<!--' has no '-->' on its own line. Nothing is hidden — only a " \
+                      "balanced single-line comment is a comment — but finish it or remove it: " \
+                      "comment-intended text is being read as board content. For longer notes, " \
+                      "stack single-line comments."
+        end
+        if respliced
+          findings << "comment stripping only settled after a second pass — fragments spliced " \
+                      "into a comment no single reading of the board contains, and text may " \
+                      "have been swallowed with them. Rewrite the line without nested '<!--' " \
+                      "fragments."
+        end
+        findings.concat(missing_sections(visible_text))
+        findings.concat(stray_bullets(visible_text))
+        findings.concat(date_findings(visible_text))
+        findings
+      end
+
+      # The six sections the counters read, exactly as the skill names them.
+      SECTIONS = [ "In flight", "Backlog", "Waiting", "Inbox", "To read", "Deadlines" ].freeze
+
+      # The section invariant, checked directly: each of the six canonical
+      # sections is present as an EXACT heading. A near-miss heuristic at
+      # this spot was at the wrong depth — it missed the commonest
+      # quiet-zero typos ('## inbox', '## In Flight', '##  Inbox' all
+      # disengaged every counter in silence) while permanently nagging the
+      # legitimate sibling pattern ('## In flight — parked' beside the
+      # real section). The claim was never "no heading resembles a
+      # section"; it is "every section exists", and checking that subsumes
+      # every typo, decoration, and deletion class at once.
+      def missing_sections(visible_text)
+        present = visible_text.each_line.map do |line|
+          line.chomp.rstrip.sub(/\A## /, "") if line.start_with?("## ")
+        end.compact
+        (SECTIONS - present).map do |name|
+          "board has no '## #{name}' section — the counters match that heading exactly, so " \
+            "its class of lines has nowhere to land. Restore it; a re-spelled or decorated " \
+            "variant does not count."
+        end
+      end
+
+      # The three date shapes, checked over text the caller already made
+      # visible — grammar() strips once and every pass here reads that one
+      # strip, through visible_section_lines.
+      def date_findings(visible_text)
+        findings = []
+        visible_section_lines(visible_text, "Inbox").each do |line|
+          next if line_date(line)
+
+          findings << "Inbox line carries no leading '- YYYY-MM-DD' date, so the oldest-capture " \
+                      "counter cannot see it: #{line.strip}"
+        end
+        visible_section_lines(visible_text, "Deadlines").each do |line|
+          next if line_date(line)
+
+          findings << "Deadlines line carries no leading '- YYYY-MM-DD' date, so the 7-day " \
+                      "warning cannot see it: #{line.strip}"
+        end
+        visible_section_lines(visible_text, "Waiting").each do |line|
+          next if chase_date(line)
+
+          findings << "Waiting line carries no 'chase YYYY-MM-DD' date, so the past-chase " \
+                      "counter cannot see it: #{line.strip}"
+        end
+        findings
+      end
+
+      # `past_first_heading` is exactly what it says: the pass covers the
+      # whole board body from the first section on — the sections' order is
+      # the board's own, and a stray bullet between two sections is as
+      # invisible to the counters as one inside them. Callers hand this the
+      # board's VISIBLE text; grammar() strips comments once for the whole
+      # pass, because a bulleted example inside documentation is not a
+      # board line, and flagging one turned a comment into a refusal at
+      # every Stop until the documentation was deleted.
+      def stray_bullets(text)
+        past_first_heading = false
+        text.to_s.each_line.with_object([]) do |line, acc|
+          past_first_heading = true if line.start_with?("## ")
+          next unless past_first_heading && line.match?(STRAY_BULLET)
+
+          acc << "board line does not start with '- ' at column zero, so no counter " \
+                 "can see it: #{line.strip}"
+        end
+      end
+    end
+  end
+end