okf-pro 1.0.0

data/lib/okf/pro/scaffold.rb

@@ -0,0 +1,258 @@
+# frozen_string_literal: true
+
+require "fileutils"
+
+module OKF
+  module Pro
+    # `okf pro setup` and `okf pro upgrade` — the generator, and the one
+    # thing it may safely do twice.
+    #
+    # TWO CLASSES OF FILE, drawn by OWNERSHIP rather than by subject matter.
+    #
+    #   GEM-OWNED   the hook wrapper, the pre-commit hook, the workflow, the
+    #               skill. These carry the fail-closed contract and the exit-code
+    #               protocol; they must track the gem or a gate goes quietly
+    #               wrong. `upgrade` rewrites them outright.
+    #   SEEDED      CLAUDE.md, .gitignore, .claude/settings.json, and the whole
+    #               of .okf/. Written once, and the adopter's from that moment.
+    #
+    # The split is not knowledge-versus-machinery, which is the obvious cut and
+    # the wrong one: `CLAUDE.md` at a repo root is the adopter's own
+    # agent-instruction file, `.gitignore` accumulates project entries from day
+    # one, and `settings.json` is where they add hooks of their own. Classing
+    # those as machinery makes `upgrade` destroy exactly the hand-merge that
+    # adopting this thing asked them to perform.
+    #
+    # WHAT HAPPENS ON A COLLISION. A file the template wants and the adopter
+    # already has is written beside it as `<path>.okf-pro-new`, with a merge
+    # instruction printed. A stale one is refreshed rather than doubled — there
+    # is never a `.okf-pro-new.okf-pro-new`.
+    #
+    # Except inside `.okf/`. A bundle that already exists is a bundle already
+    # adopted, and eleven shadow files scattered through someone's knowledge is
+    # not a merge prompt, it is litter — in a directory whose whole value is
+    # that everything in it is deliberate. There, only missing files are added.
+    #
+    # ATOMICITY, STATED HONESTLY: each file is written to a temp path in its own
+    # destination directory and renamed, so no half-written file ever exists.
+    # A twenty-file sequence is not atomic as a *set*, and nothing here pretends
+    # otherwise. The real safety is that `setup` is idempotent and re-runnable.
+    module Scaffold
+      ROOT = File.expand_path("template", __dir__)
+
+      # `upgrade` rewrites these.
+      GEM_DIR = File.join(ROOT, "gem")
+
+      # `setup` writes these once; nothing ever rewrites them.
+      SEED_DIR = File.join(ROOT, "seed")
+
+      SUFFIX = ".okf-pro-new"
+
+      # Stored without its dot and renamed on write. As a real dotfile in this
+      # gem's tree it would be a live gitignore governing its own directory —
+      # silently deciding what `git ls-files` reports, and therefore what ships.
+      DOTFILES = { "gitignore" => ".gitignore" }.freeze
+
+      # A wrapper without +x does not refuse: git silently skips a
+      # non-executable hook, and the shell reports 127, which the hook protocol
+      # reads as non-blocking. Both scripts are asserted executable on the
+      # generated output, not merely here.
+      EXECUTABLE = [ ".claude/hooks/run", ".githooks/pre-commit" ].freeze
+
+      # The skill alone, for `okf pro skill <dest>`.
+      SKILL_REL = ".claude/skills/okf-pro/SKILL.md"
+
+      module_function
+
+      def setup(dest, out:, err:)
+        dest = File.expand_path(dest.to_s)
+
+        refusal = flat_layout_refusal(dest)
+        if refusal
+          err.puts refusal
+          return BLOCK
+        end
+
+        report(out, write_tree(GEM_DIR, dest) + write_tree(SEED_DIR, dest), dest, "setup")
+        PASS
+      end
+
+      def upgrade(dest, out:, err:)
+        dest = File.expand_path(dest.to_s)
+
+        unless File.directory?(dest)
+          err.puts "okf pro upgrade — #{dest} is not a directory."
+          return BLOCK
+        end
+
+        # The gem-owned four are rewritten; the seeded ones are only completed.
+        # An `upgrade` that overwrote a seeded file would take the adopter's own
+        # CLAUDE.md with it, and an `upgrade` that staged every one of them would
+        # bury the four files that actually changed under thirteen that did not.
+        report(out, write_tree(GEM_DIR, dest, overwrite: true) + write_tree(SEED_DIR, dest), dest, "upgrade")
+        PASS
+      end
+
+      # The destination tree is created — `.claude/skills/okf-pro` is the
+      # natural place and `.claude/skills` often does not exist yet, so refusing
+      # on a missing parent would refuse the common case to guard against a typo
+      # that costs one `rm -r`.
+      #
+      # Overwritten rather than staged, unlike the seeded files: the skill is
+      # gem-owned, and refreshing it is the entire reason this verb exists.
+      def skill(dest, out:, err:)
+        dest = File.expand_path(dest.to_s)
+
+        if File.exist?(dest) && !File.directory?(dest)
+          err.puts "okf pro skill — #{dest} is a file; the skill is a directory holding SKILL.md."
+          return BLOCK
+        end
+
+        # Every file, not just the entry point. The skill was one file once, and
+        # an installer that kept copying only `SKILL.md` would install something
+        # that LOOKS installed — the entry point present, its index listing
+        # guides, and every link in it dead. Nothing errors; the agent simply
+        # cannot follow its own instructions.
+        source = File.join(GEM_DIR, File.dirname(SKILL_REL))
+        results = entries(source).map do |rel|
+          copy(File.join(source, rel), File.join(dest, rel), overwrite: true)
+        end
+
+        report(out, results, dest, "skill")
+        PASS
+      end
+
+      # Every path a template directory holds, relative, dotfiles included.
+      #
+      # A plain glob returns `["CLAUDE.md"]` and nothing else here: without
+      # FNM_DOTMATCH it does not match a leading dot, and this template is
+      # almost entirely dotfiles. `.` and `..` are rejected explicitly, which
+      # the flag makes necessary.
+      def entries(template)
+        Dir.glob(File.join(template, "**", "*"), File::FNM_DOTMATCH)
+           .reject { |path| [ ".", ".." ].include?(File.basename(path)) }
+           .select { |path| File.file?(path) }
+           .map { |path| path[(template.size + 1)..-1] }
+           .sort
+      end
+
+      # Where a template-relative path lands in the destination.
+      def target_rel(rel)
+        parts = rel.split("/")
+        parts[-1] = DOTFILES.fetch(parts.last, parts.last)
+        parts.join("/")
+      end
+
+      def write_tree(template, dest, overwrite: false)
+        entries(template).map do |rel|
+          copy(File.join(template, rel), File.join(dest, target_rel(rel)),
+            overwrite: overwrite, rel: target_rel(rel))
+        end
+      end
+
+      # One file. Returns [ :written | :staged | :kept, path ] — the verb's
+      # report is built from these rather than printed here, so that the whole
+      # decision about what happened lives in one place.
+      #
+      # `rel` is the path *within the destination*, and it is what the `.okf/`
+      # exemption is asked about. Asking the absolute path would put every file
+      # of a repository that happens to live under a directory named `.okf` on
+      # the exempt side, which is a plausible enough path (`~/.okf/notes`) to be
+      # worth not getting wrong.
+      def copy(source, target, overwrite: false, rel: nil)
+        unless File.exist?(target)
+          write_atomically(target, File.binread(source), executable?(target))
+          return [ :written, target ]
+        end
+        return [ :written, target ] if overwrite && write_atomically(target, File.binread(source), executable?(target))
+        return [ :kept, target ] if inside_bundle?(rel) || File.binread(target) == File.binread(source)
+
+        staged = "#{target}#{SUFFIX}"
+        write_atomically(staged, File.binread(source), executable?(target))
+        [ :staged, staged ]
+      end
+
+      # The `.okf/` exemption: a bundle that exists is a bundle already adopted,
+      # and eleven shadow files through someone's knowledge is litter, not a
+      # merge prompt. `rel` is nil for the single-file `skill` verb, which is
+      # gem-owned and overwrites before reaching here.
+      def inside_bundle?(rel)
+        rel.to_s.split("/").first == BundleRoot::DIR
+      end
+
+      def executable?(target)
+        EXECUTABLE.any? { |rel| target.end_with?("/#{rel}") }
+      end
+
+      def write_atomically(target, content, executable)
+        FileUtils.mkdir_p(File.dirname(target))
+        tmp = "#{target}.okf-pro-tmp-#{Process.pid}"
+        File.binwrite(tmp, content)
+        File.chmod(executable ? 0o755 : 0o644, tmp)
+        File.rename(tmp, target)
+        true
+      ensure
+        File.unlink(tmp) if tmp && File.exist?(tmp)
+      end
+
+      # `setup` into a bundle whose root IS the repository root.
+      #
+      # Writing `.okf/index.md` beside it collides with nothing, so the naive
+      # generator succeeds and leaves two bundle roots in one directory — the
+      # exact state `Audit.ambiguous_layout` exists to report, where the three
+      # doors disagree until one of the two is retired. Refusing is the only
+      # honest answer: the migration is the adopter's to make, and it is one
+      # `git mv` they can see.
+      # Asked with `root_kind`, the same predicate `Audit.ambiguous_layout` asks,
+      # because this refusal cites that finding by name. It asked `bundle?` —
+      # `index.md` alone — while the finding needs index.md PLUS board.md or
+      # log.md, or an `okf_version` in the frontmatter. So every Jekyll section,
+      # Hugo directory and repo with an `index.md` README was refused, and told
+      # to `git mv` files that have nothing to do with OKF, for an ambiguity the
+      # audit would never have reported. A refusal that names a finding has to
+      # be answering the question that finding asks.
+      def flat_layout_refusal(dest)
+        return nil unless File.directory?(dest)
+        return nil if BundleRoot.bundle?(File.join(dest, BundleRoot::DIR))
+        return nil if BundleRoot.root_kind(dest).nil?
+
+        "okf pro setup — #{dest} is already an OKF bundle at its own root, and this scaffold " \
+          "puts the bundle under #{BundleRoot::DIR}/. Writing one here would leave two bundle roots " \
+          "in one directory, which the audit reports as an ambiguous layout and the three doors " \
+          "then disagree about. Move it first:\n  " \
+          "mkdir #{BundleRoot::DIR} && git mv index.md log.md <your dirs> #{BundleRoot::DIR}/\n" \
+          "then run setup again."
+      end
+
+      def report(out, results, dest, verb)
+        written = results.select { |kind, _| kind == :written }
+        staged = results.select { |kind, _| kind == :staged }
+
+        out.puts "okf pro #{verb} — #{dest}"
+        out.puts "  #{written.size} written, #{staged.size} staged, #{results.size - written.size - staged.size} left alone"
+        return if staged.empty?
+
+        out.puts "  These already existed and are yours, so the template's version is beside them:"
+        staged.each { |entry| out.puts "    #{entry.last}" }
+        out.puts "  Merge what you want from each, then delete it. #{ignore_note(dest)}"
+      end
+
+      # The last line of that report is a claim about the reader's own tree, so
+      # it is read from the tree rather than assumed.
+      #
+      # It was assumed, and it was false in exactly the case that matters: when
+      # `.gitignore` is itself the collision, the adopter's own file is what
+      # stays on disk and the template's — the one carrying `*#{SUFFIX}` — is
+      # what got staged beside it. Telling them it is already ignored is how the
+      # staged copies end up committed with nothing ever saying so, which is the
+      # failure the seeded `.gitignore` comment exists to name.
+      def ignore_note(dest)
+        gitignore = File.join(dest, ".gitignore")
+        ignored = File.file?(gitignore) && Pro.read_text(gitignore).include?("*#{SUFFIX}")
+        return "`.gitignore` already ignores *#{SUFFIX}." if ignored
+
+        "Add `*#{SUFFIX}` to `.gitignore` first, or they get committed."
+      end
+    end
+  end
+end

data/lib/okf/pro/shell_guard.rb

@@ -0,0 +1,164 @@
+# frozen_string_literal: true
+
+module OKF
+  module Pro
+    # The door the other guards do not cover.
+    #
+    # `guard-verified` and `journal-guard` are PreToolUse on Edit/Write/
+    # MultiEdit — they read a `file_path` and the text being added. A shell
+    # command has neither: `cat > .okf/reference/x.md <<'EOF' … verified: …`
+    # writes the same bytes with no file_path to scope on and no new_string
+    # to scan, so every trust rule in this repo used to step aside for a tool
+    # the agent already has. That is the contract's forbidden case — not a
+    # gate that refused, a gate that was never asked.
+    #
+    # This cannot parse shell, and does not pretend to. It answers one
+    # narrow question — does this command look like it writes markdown
+    # inside a bundle? — and routes the answer to the owner, who can read
+    # the command. Asking is the honest verdict for a check that cannot
+    # decide: it costs one prompt when wrong, and unattended it fails
+    # closed, exactly like the attestation gate it backstops.
+    module ShellGuard
+      # Mutation, in the spellings a shell actually uses. Redirections and
+      # in-place editors first, then the file-movers.
+      MUTATORS = [
+        # `cat … > file`, `… >> file`, with two exclusions, both of them
+        # reads this used to call writes. A guard that fires on reads is a
+        # guard people switch off.
+        #
+        # Redirections to /dev/ are excluded: `2>/dev/null` is a read-only
+        # command discarding its stderr, and counting it as a write made
+        # every `grep … 2>/dev/null` in a repo that happens to contain
+        # markdown a prompt.
+        #
+        # An ASCII arrow is excluded by the lookbehind, because a `>` after
+        # `-` or `=` is not a position a redirection can occupy. Nothing
+        # anchored this before, so `-->` and `=>` read as writes — worst of
+        # all in a bundle, where `-->` closes the HTML comment the skill
+        # mandates on every keyed rule and is also mermaid's edge, and `=>`
+        # is in every quoted Ruby hash. The second alternative covers the
+        # doubled arrows (`->>`, `-->>`), whose trailing `>` is preceded by
+        # a `>` rather than by the `-` that gives it away.
+        %r{(?<![-=]|[-=]>)>{1,2}[[:blank:]]*(?!/dev/)[^|&\s]}, # cat … > file, … >> file
+        /\btee\b/,
+        /\b(?:sed|perl|ruby|python3?|node|awk)\b[^|;]*-i\b/, # in-place editors
+        /\b(?:cp|mv|rm|install|truncate|dd|rsync|ln)\b/,
+        /\b(?:File\.write|File\.open|open\([^)]*['"]w)/ # inline interpreter writes
+      ].freeze
+
+      # A markdown path anywhere in the command, minus the quoting and
+      # separators a shell puts around it.
+      MARKDOWN = %r{[^\s'"`|;&()<>]*\.md\b}.freeze
+
+      # What separates one COMMAND from the next, for the one question below
+      # that has to look past the whole string.
+      #
+      # A single `|` is deliberately absent: a pipeline is one command, not
+      # two, and splitting on it put this gem's own redirect target in a
+      # segment of its own — `okf pro snapshot | tee -a .okf/log.md`, the
+      # prescribed way to append the Snapshot line, was recorded as friction.
+      # That is the good path counted as evidence against itself, which is the
+      # one failure the exclusion exists to prevent. `||` is still a separator
+      # and is listed first so the doubled form wins the alternation.
+      SEPARATORS = /&&|\|\||;|\n/.freeze
+
+      module_function
+
+      def check(event)
+        command = event.command
+        return [] if command.empty?
+        return [] unless MUTATORS.any? { |m| command.match?(m) }
+
+        # Scoped like every other guard: no bundle here, not this repo's
+        # business. The cwd is the only anchor a shell command offers —
+        # there is no file_path to walk up from — so this is the one check
+        # that must root through it.
+        root = BundleRoot.enclosing(event.cwd)
+        return [] if root.nil?
+        return [] unless touches_bundle?(command, root)
+
+        # Recorded here rather than at a hook event of its own, because
+        # `settings.json` is SEEDED: a new registration would never reach an
+        # adopter through `upgrade`, so friction has to ride a path already
+        # wired. This is the honest point for it — a markdown write inside the
+        # bundle, arriving through Bash, is by definition a thing the verbs did
+        # not cover. Own commands are skipped, or the good path would be
+        # counted as evidence against itself.
+        #
+        # It records INTENT: PreToolUse fires before the owner may deny.
+        unless own_write?(command)
+          Friction.record(root, "shell", Friction.classify_command(command), command.lines.first.to_s.strip[0, 200])
+        end
+
+        { "ask" => "This shell command looks like it writes markdown inside the bundle:\n  " \
+                   "#{command.lines.first.to_s.strip}\n" \
+                   "Shell writes bypass the trust guards — nothing checked this for a forged " \
+                   "'verified:' block or an edit to a past journal day. Approve only if you " \
+                   "have read the command and it does neither; otherwise deny and use Edit or " \
+                   "Write, which the guards can see." }
+      end
+
+      # Whether the WRITE belongs to this gem — not whether the command mentions
+      # it. `Friction.own_command?` exists so the good path is not counted as
+      # evidence against itself (`okf pro snapshot >> .okf/log.md` is the
+      # prescribed way to add the Snapshot line), and asking it of the whole
+      # string let a mention anywhere suppress the record: `okf pro state &&
+      # cat notes.md > .okf/board.md` prompted the owner and counted nothing.
+      # An agent chaining a read with a write is exactly the pattern that
+      # produces it, so the under-count was in the commonest shape.
+      #
+      # So it is asked of the SEGMENT that carries the mutator. A segment with
+      # no mutator is nobody's write — `cd repo && okf pro promote alpha` is
+      # still this gem's — and a mutator in a segment this gem does not own is
+      # a hand-write whatever else the line says.
+      #
+      # Splitting on separators is NOT shell parsing and may not become one:
+      # a separator inside quotes mis-splits, and the only consequence of that
+      # is a telemetry row. The PROMPT above is decided from the whole command
+      # and is unaffected, so nothing about the guard's safety rides on this.
+      #
+      # The confessed residue, since a bounded error is only bounded if it is
+      # written down: a `;` or `&&` inside quoted content splits a command that
+      # is genuinely this gem's, and the fragment carrying the mutator word is
+      # then read as somebody else's write; and a capture whose TEXT names
+      # `board.md` trips the laundering guard above. Both over-count. That is
+      # the lesser error — an over-count points a maintainer at a verb that
+      # already exists, while the under-counts these replaced hid the commonest
+      # shape there is and the worst one there is — and neither can refuse
+      # anything.
+      def own_write?(command)
+        segments = command.to_s.split(SEPARATORS)
+        return false unless segments.any? { |segment| Friction.own_command?(segment) }
+        # A pipeline is one command, and that must not become a way to launder
+        # a hand-write: `okf pro board | sed s/a/b/ > .okf/board.md` begins with
+        # this gem and ends by regenerating the board, which is failure mode 07
+        # by name. No verb pipes into a path a verb covers — `snapshot` has no
+        # `--write` and appends to `log.md`, which no verb covers — so an own
+        # command aimed at the board is friction whatever produced the bytes.
+        return false if Friction.classify_command(command) == "board.md"
+
+        segments.none? do |segment|
+          !Friction.own_command?(segment) && MUTATORS.any? { |m| segment.match?(m) }
+        end
+      end
+
+      # The bundle by name is enough on its own. A markdown path is enough
+      # only if it could be in the bundle: relative — resolved against a cwd
+      # already known to be inside one — or absolute and under the root. An
+      # absolute path elsewhere is not this repo's markdown, and treating a
+      # gem's CHANGELOG.md as a bundle write is how the prompt stopped
+      # carrying information.
+      #
+      # Relative paths stay conservative rather than being resolved against
+      # the cwd, because a `cd` earlier in the command would make that
+      # resolution a guess, and this guard asks when it cannot decide.
+      def touches_bundle?(command, root)
+        return true if command.match?(/#{Regexp.escape(BundleRoot::DIR)}\b/)
+
+        command.scan(MARKDOWN).any? do |path|
+          !path.start_with?("/") || path.start_with?("#{root}/")
+        end
+      end
+    end
+  end
+end

data/lib/okf/pro/snapshot.rb

@@ -0,0 +1,156 @@
+# frozen_string_literal: true
+
+module OKF
+  module Pro
+    # Rule 2's counters, derived. This is derivation returned as a *checker*:
+    # it computes the mechanical line and verifies the one a person appended —
+    # it never writes one. Agent Drift killed the generator (a regenerated view
+    # drops a task silently); a checker that disagrees out loud has no way to
+    # drop anything silently, which is why it gets to exist first.
+    module Snapshot
+      # The line's vocabulary, in the order the line reads. Parse patterns are
+      # anchored on the field names so a hand-typed line with extra spacing
+      # still parses, and a line missing a field says so as nil rather than
+      # borrowing a neighbour's number. "in flight" requires the slash so the
+      # phrase inside "deadlines within 7d not in flight" cannot satisfy it.
+      #
+      # `oldest` takes an optional sign, and it is the only field that can:
+      # every other counter is a count, and `oldest` is a SUBTRACTION. A
+      # capture dated in the future — one mistyped year — gives a negative age,
+      # `render` wrote `oldest -365d`, and a pattern demanding a digit straight
+      # after `oldest ` read that as nothing at all. `verify` then disagreed
+      # with the line `render` had just produced, so the stop gate refused and
+      # offered as the fix the very line it was refusing. Pasting it refused
+      # again: a deadlock with no self-service exit.
+      #
+      # The age is NOT clamped to zero, deliberately. Clamping would make the
+      # gate self-consistent by making the counter lie, and `oldest 0d` on a
+      # line nobody can explain is the quiet-wrong-number failure this whole
+      # module exists to refuse. A negative age is the honest reading of a
+      # future-dated capture, and it is visible in the log where a person will
+      # ask about it.
+      PATTERNS = {
+        "inbox" => /inbox (\d+)/,
+        "oldest" => /oldest (-?\d+)d/,
+        "in flight" => %r{in flight (\d+)/\d+},
+        "cap" => %r{in flight \d+/(\d+)},
+        "waiting" => /waiting (\d+)/,
+        "past chase" => /\((\d+) past chase\)/,
+        "backlog" => /backlog (\d+)/,
+        "to read" => /to read (\d+)/,
+        "unverified briefings" => /unverified briefings (\d+)/,
+        "conflicts open" => /conflicts open (\d+)/,
+        "deadlines within 7d not in flight" => /deadlines within 7d not in flight (\d+)/,
+        "projects with 0 concepts" => /projects with 0 concepts (\d+)/
+      }.freeze
+
+      module_function
+
+      # `board:` and `concepts:` are the same courtesy Pairing.failures
+      # extends: a caller that already paid for the read hands it over. The
+      # stop gate reads the board and parses the bundle once for all of its
+      # checks; without the seam it paid twice per Stop.
+      def counters(root, today: Date.today, board: nil, concepts: nil)
+        board ||= Pro.read_text(File.join(root, "board.md"))
+        concepts ||= ::OKF::Bundle::Reader.read(root).concepts
+        # One strip for all twelve counters — every Board.count call was
+        # re-running the whole comment strip, ~10 times per Stop.
+        vis = Board.visible(board)
+        budget = Board.budget(vis)
+        inbox = Board.visible_section_lines(vis, "Inbox")
+        waiting = Board.visible_section_lines(vis, "Waiting")
+        ages = inbox.map { |l| Board.line_date(l) }.compact
+                    .map { |d| (today - d).to_i }
+        chases = waiting.map { |l| Board.chase_date(l) }.compact
+
+        {
+          "inbox" => inbox.size,
+          "oldest" => ages.max || 0,
+          "in flight" => Board.visible_section_lines(vis, "In flight").size,
+          "cap" => budget ? budget.cap : 0,
+          "waiting" => waiting.size,
+          "past chase" => chases.count { |d| d < today },
+          "backlog" => Board.visible_section_lines(vis, "Backlog").size,
+          "to read" => Board.visible_section_lines(vis, "To read").size,
+          "unverified briefings" => Pairing.unverified_ids(concepts).size,
+          "conflicts open" => conflicts(vis),
+          "deadlines within 7d not in flight" => looming_deadlines(vis, today).size,
+          "projects with 0 concepts" => empty_projects(root).size
+        }
+      end
+
+      def line(root, today: Date.today, board: nil, concepts: nil)
+        render(counters(root, today: today, board: board, concepts: concepts))
+      end
+
+      def render(c)
+        "* **Snapshot**: inbox #{c["inbox"]} (oldest #{c["oldest"]}d) " \
+          "· in flight #{c["in flight"]}/#{c["cap"]} " \
+          "· waiting #{c["waiting"]} (#{c["past chase"]} past chase) " \
+          "· backlog #{c["backlog"]} · to read #{c["to read"]} " \
+          "· unverified briefings #{c["unverified briefings"]} " \
+          "· conflicts open #{c["conflicts open"]} " \
+          "· deadlines within 7d not in flight #{c["deadlines within 7d not in flight"]} " \
+          "· projects with 0 concepts #{c["projects with 0 concepts"]}"
+      end
+
+      def parse(line)
+        PATTERNS.transform_values do |pattern|
+          match = line.to_s.match(pattern)
+          match && match[1].to_i
+        end
+      end
+
+      # The appended line against the bundle it summarises. Field by field, so
+      # the refusal names what drifted instead of waving at the whole line —
+      # and the recomputed line is in the message, because the fix is a paste.
+      def verify(root, line, today: Date.today, board: nil, concepts: nil)
+        want = counters(root, today: today, board: board, concepts: concepts)
+        got = parse(line)
+        wrong = want.reject { |key, value| got[key] == value }
+        return [] if wrong.empty?
+
+        detail = wrong.map { |key, value| "#{key} is #{value}, the line says #{got[key] || "nothing"}" }
+        [ "— the Snapshot line disagrees with the bundle it summarises: #{detail.join("; ")}.\n  " \
+          "The mechanical line, recomputed:\n  #{render(want)}" ]
+      end
+
+      # Conflict lines are dated captures wherever they sit — Inbox by rule,
+      # but a line that migrated to Backlog is still an open conflict.
+      def conflicts(board)
+        # visible() is a fixpoint, so a caller handing over already-visible
+        # text (counters does) costs one no-op scan, not a second strip.
+        Board.visible(board).each_line.count { |l| l.start_with?("- ") && l.include?("Resolve:") }
+      end
+
+      # Crack 2's confession: deadlines due within the window — or already due
+      # — that share no project link with any in-flight line. A deadline line
+      # with no link cannot be paired, so it counts: the board cannot show
+      # anyone is on it, and "probably someone is" is not a counter.
+      def looming_deadlines(board, today, window: 7)
+        vis = Board.visible(board)
+        covered = Board.visible_section_lines(vis, "In flight").flat_map { |l| project_slugs(l) }
+        Board.visible_section_lines(vis, "Deadlines").select do |line|
+          date = Board.line_date(line)
+          next false unless date && date <= today + window
+
+          (project_slugs(line) & covered).empty?
+        end
+      end
+
+      def project_slugs(line)
+        Board.targets(line).map { |t| t[%r{\A/projects/([^/\s]+)}i, 1]&.downcase }.compact
+      end
+
+      # An open project holding nothing but its own index: work happening with
+      # no knowledge landing — the blind spot the structure itself created.
+      def empty_projects(root)
+        Pairing.open_projects(root).select do |name|
+          Dir.glob(File.join(root, "projects", name, "**", "*.md"))
+             .reject { |f| File.basename(f) == "index.md" }
+             .empty?
+        end
+      end
+    end
+  end
+end