okf 1.12.0 → 2.0.0

data/lib/okf/cli/command.rb

@@ -23,6 +23,11 @@ module OKF
       # it is installed instead of the first time a user types its verb.
       DUCK_TYPE = %i[id group help_rows hidden? new].freeze
 
+      # Every key a filter flag can set. One list, read by both the narrowing
+      # itself and the "is anything narrowing?" guard, so adding a filter cannot
+      # leave one of them behind.
+      FILTER_KEYS = %i[type area dir tag status trust].freeze
+
       class << self
         # The verb this answers to, as a Symbol. The registry is keyed on it.
         def id
@@ -188,41 +193,103 @@ module OKF
           end
         end
         parser.on("--tag TAG", "only concepts carrying this tag") { |v| options[:tag] = v } if keys.include?(:tag)
+        # The read-side payoff of v0.2, and the two questions no v0.1 tool could
+        # answer: which concepts nobody has verified, and which are on their way
+        # out. Unconditional — every filtering verb narrows the same catalog
+        # rows, and on a v0.1 bundle the answers still read (`stable` for every
+        # concept, `unverified` for every concept — §13.1, not an error).
+        parser.on("--status STATUS", "only concepts at this lifecycle status (draft | stable | deprecated)") do |v|
+          options[:status] = v
+        end
+        parser.on("--trust TIER", "only concepts at this trust tier (unverified | machine-confirmed | human-reviewed)") do |v|
+          options[:trust] = v
+        end
       end
 
-      def filter_entries(entries, options)
+      # The argument is resolved once per view, not once per entry: the `root`
+      # alias below has to consult the bundle's own directories, and that is a
+      # question about the whole set rather than about the row in hand.
+      #
+      # +dirs+ is that set, and every in-tree caller passes it (see #dir_scope)
+      # rather than deriving it from +entries+ — the catalog knows only
+      # directories that hold *concepts*, so a `root/` carrying an index.md and
+      # nothing else was invisible here while `dirs` and `index` (which read
+      # Bundle#directories) saw it. Two answers to one question about one
+      # bundle is how the alias survived its own fix.
+      #
+      # The default is a compatibility promise, not a shortcut: this base is
+      # what every plugin verb inherits, and 1.12.0 shipped the two-argument
+      # shape. An out-of-tree caller that never learned the third argument gets
+      # exactly the resolution it was written against — the alias folds with no
+      # directory set consulted — no better and no worse.
+      # The row rules live in Bundle::RowFilter, shared with the MCP shell;
+      # this layer keeps only what is the CLI's own — the deprecated --area
+      # (a top_dir compare no other surface offers) and the argument spelling
+      # (the `root`/`.` aliases resolved against the bundle's real dirs).
+      def filter_entries(entries, options, dirs = nil)
+        area = options[:area] && fold_area(options[:area], dirs)
+        base = options[:dir] && fold_dir(options[:dir], dirs)
         entries.select do |entry|
-          (options[:type].nil? || fold(entry[:type]) == fold(options[:type])) &&
-            (options[:area].nil? || fold(entry[:top_dir]) == fold_area(options[:area])) &&
-            (options[:dir].nil? || under_dir?(entry[:dir], options[:dir])) &&
-            (options[:tag].nil? || entry[:tags].any? { |tag| fold(tag) == fold(options[:tag]) })
+          (area.nil? || fold(entry[:top_dir]) == area) &&
+            Bundle::RowFilter.matches?(entry, type: options[:type], dir: base, tag: options[:tag],
+              status: options[:status], trust: options[:trust])
         end
       end
 
+      # The directory set only when a flag is going to consult it. Deriving it
+      # walks every path up to the root, and #filter_entries reads it solely to
+      # resolve the `root`/`--area` aliases — a plain listing, or a type/tag
+      # narrowing, never needs the walk.
+      def dir_scope(folder, options)
+        options[:dir] || options[:area] ? folder.directories : nil
+      end
+
       # The one rule --dir is built on: a dir names itself and everything beneath
       # it. `--dir foo` reaches foo/bar, `--dir foo/bar` narrows, and `--dir .`
       # needs no special case at all — nothing starts with "./", so the root
       # selects only what lives directly in it.
-      def under_dir?(entry_dir, wanted)
-        entry = fold(entry_dir)
-        path = fold_dir(wanted)
-        entry == path || entry.start_with?("#{path}/")
+      #
+      # +path+ arrives already folded, through #fold_dir for a user's argument
+      # and #fold for a stored one. A stored dir is never an alias — that is the
+      # distinction the old signature could not make, and it is what had a row
+      # named `root` counting the bundle root's subtree instead of its own.
+      # The comparison itself is Bundle::RowFilter's (fold is idempotent).
+      def under_dir?(entry_dir, path)
+        Bundle::RowFilter.under_dir?(entry_dir, path)
       end
 
       def fold(value)
         value.to_s.downcase
       end
 
-      def fold_area(value)
+      def fold_area(value, known = nil)
         folded = trim_slash(fold(value))
-        folded == "root" ? "(root)" : folded
+        folded == "root" && !names_dir?(known, "root") ? "(root)" : folded
       end
 
       # `.` is the stored spelling of the root everywhere; `root` is the one a
       # shell needs no quoting for, and the only reason the two exist.
-      def fold_dir(value)
+      #
+      # A bundle that really has a `root/` directory owns the word, and +known+
+      # — the directories that bundle actually holds — is what decides. The
+      # alias is a convenience; being able to name a directory at all is not, so
+      # the convenience yields. Without this, `--dir root` answered for the
+      # bundle root in such a bundle: the wrong concepts, exit 0, nothing said.
+      def fold_dir(value, known = nil)
         folded = trim_slash(fold(value))
-        folded.empty? || folded == "root" ? "." : folded
+        return "." if folded.empty?
+
+        folded == "root" && !names_dir?(known, "root") ? "." : folded
+      end
+
+      # Does the bundle hold a directory by this name? An ancestor counts: a
+      # bundle whose only concept sits in `root/deep` still has a `root`, and
+      # `--dir root` has to reach it by the prefix rule above.
+      def names_dir?(known, name)
+        Array(known).any? do |dir|
+          folded = fold(dir)
+          folded == name || folded.start_with?("#{name}/")
+        end
       end
 
       # The human views print a directory with the slash that says it is one —
@@ -307,7 +374,7 @@ module OKF
 
         stored = known.each_with_object({}) { |dir, out| out[fold(dir)] = dir }
         Array(options[:dirs]).each_with_object([]) do |path, out|
-          base = fold_dir(path)
+          base = fold_dir(path, known)
           next unless stored.key?(base)
 
           current = dir_parent(base)
@@ -331,7 +398,7 @@ module OKF
       # they do not define one. The ancestor chain is unioned on top by the
       # caller, which is also what tells a row apart from context.
       def select_dirs(dirs, options)
-        bases = Array(options[:dirs]).map { |path| fold_dir(path) }
+        bases = Array(options[:dirs]).map { |path| fold_dir(path, dirs) }
         depth = options[:depth]&.to_i
         return dirs if bases.empty? && depth.nil?
         # No --dir means the whole bundle is the starting point, which is *not*
@@ -373,13 +440,20 @@ module OKF
 
       # The ids the filters select, resolved through the catalog metadata — or nil
       # when no filter is active, meaning keep everything.
-      def filter_ids(folder, options)
-        return nil if options[:type].nil? && options[:area].nil? && options[:dir].nil? && options[:tag].nil?
+      #
+      # +dirs+ overrides the folder's own directory set, which is what a
+      # multi-bundle run passes: the `root` alias is a fact about a bundle, so
+      # resolving it per folder inside a loop let one `--dir root` mean the
+      # `root/` subtree in one bundle and the bundle root in the next, merged
+      # into a single ranking with nothing saying so. One invocation, one
+      # meaning — see Search#multi_search.
+      def filter_ids(folder, options, dirs = nil)
+        return nil if FILTER_KEYS.none? { |key| options[key] }
 
-        filter_entries(folder.catalog, options).map { |entry| entry[:id] }
+        filter_entries(folder.catalog, options, dirs || dir_scope(folder, options)).map { |entry| entry[:id] }
       end
 
-      # §9 best-effort: the graph is built from concepts that parse. Surface any that
+      # §11 best-effort: the graph is built from concepts that parse. Surface any that
       # the reader could not parse (to stderr, so JSON on stdout stays clean) rather
       # than dropping them silently.
       def report_skipped(folder)

data/lib/okf/cli/dirs.rb

@@ -79,7 +79,7 @@ module OKF
       def subtree_counts(entries)
         entries.each_with_object({}) do |entry, out|
           out[entry[:dir]] = entries.reduce(0) do |sum, other|
-            under_dir?(other[:dir], entry[:dir]) ? sum + other[:count] : sum
+            under_dir?(other[:dir], fold(entry[:dir])) ? sum + other[:count] : sum
           end
         end
       end

data/lib/okf/cli/files.rb

@@ -22,7 +22,7 @@ module OKF
       def call(argv)
         options = { json: false }
         parser = OptionParser.new do |o|
-          o.banner = "Usage: okf files <dir|@slug> [--type T] [--dir D] [--tag T] [--json]"
+          o.banner = "Usage: okf files <dir|@slug> [--type T] [--dir D] [--tag T] [--status S] [--trust T] [--json]"
           json_flags(o, options, "emit the file tree as JSON")
           projection_flags(o, options)
           filter_flags(o, options, :type, :area, :tag)
@@ -33,7 +33,7 @@ module OKF
         folder = OKF::Bundle::Folder.load(dir)
         report_skipped(folder)
         entries = folder.catalog
-        selected = filter_entries(entries, options)
+        selected = filter_entries(entries, options, dir_scope(folder, options))
         return print_files_json(dir, selected, options) if options[:json]
 
         print_files(dir, selected, entries.size)

data/lib/okf/cli/index.rb

@@ -2,7 +2,7 @@
 
 module OKF
   class CLI
-    # The progressive-disclosure map (spec §6): every directory that holds concepts
+    # The progressive-disclosure map (spec §8): every directory that holds concepts
     # or carries an index.md, with its authored index body, a type/tag rollup, its
     # child directories, and — for a directory with no index.md — the listing
     # synthesized from the concepts there. The "orient before you read" view. `--dir`
@@ -91,11 +91,11 @@ module OKF
       # deprecated flag that quietly widens is worse than one that is merely old.
       # Nothing passed keeps the whole map.
       def select_directories(entries, options)
-        areas = Array(options[:areas]).map { |area| fold_dir(area) }
+        all_dirs = entries.map { |entry| entry[:dir] }
+        areas = Array(options[:areas]).map { |area| fold_dir(area, all_dirs) }
         scoped = !options[:dirs].nil? || !options[:depth].nil?
         return [ entries, [] ] if areas.empty? && !scoped
 
-        all_dirs = entries.map { |entry| entry[:dir] }
         wanted = scoped ? select_dirs(all_dirs, options) : []
         chain = ancestor_dirs(options, all_dirs) - wanted
         selected = entries.select do |entry|

data/lib/okf/cli/lint.rb

@@ -10,12 +10,19 @@ module OKF
       LINT_CATEGORIES = {
         "Reachability" => %i[orphan not_in_index disconnected_component unlinked],
         "Backlog" => %i[missing_concept broken_index_entry],
-        "Completeness" => %i[stub missing_title missing_description missing_timestamp],
-        "Freshness" => %i[stale],
-        "Provenance" => %i[uncited_external broken_citation],
-        "Hygiene" => %i[duplicate_title unused_reference_def undefined_reference self_link]
+        "Completeness" => %i[stub missing_title missing_description missing_generated],
+        "Freshness" => %i[expired stale],
+        "Provenance" => %i[uncited_external broken_source unattributed_claim unused_source unprefixed_actor],
+        "Attestation" => %i[incomplete_computation broken_attestation_ref],
+        "Migration" => %i[legacy_timestamp legacy_citations],
+        "Hygiene" => %i[duplicate_title unused_reference_def undefined_reference self_link log_order]
       }.freeze
 
+      # `--today` reason for existing, in one line: a CI consumer wanting a
+      # reproducible `expired` report needs a fixed clock. Semver-stable API,
+      # documented in the skill's cli.md; absent, the CLI reads the wall clock —
+      # the library default (`Linter.call` with no `today:`) reads none at all.
+
       def self.id
         :lint
       end
@@ -26,20 +33,24 @@ module OKF
 
       def self.help_rows
         [
-          [ "lint      <dir|@slug> [--json] [--fail-on warn] [...]", "report curation-quality issues" ]
+          [ "lint      <dir|@slug> [--json] [--fail-on LEVEL] [...]", "report curation-quality issues" ]
         ]
       end
 
       def call(argv)
-        options = { json: false, min_body: OKF::Bundle::Linter::DEFAULT_MIN_BODY, stale_after: nil, only: nil, except: nil, fail_on: :never }
+        options = { json: false, min_body: OKF::Bundle::Linter::DEFAULT_MIN_BODY, stale_after: nil,
+                    today: nil, only: nil, except: nil, fail_on: :never }
         parser = OptionParser.new do |o|
-          o.banner = "Usage: okf lint <dir|@slug> [--json] [--min-body N] [--stale-after DUR] [--only a,b] [--except a,b] [--fail-on warn]"
+          o.banner = "Usage: okf lint <dir|@slug> [--json] [--min-body N] [--stale-after DUR] [--today DATE] " \
+                     "[--only a,b] [--except a,b] [--fail-on never|info|warn]"
           json_flags(o, options, "emit a JSON report")
           o.on("--min-body N", Integer, "stub threshold in body characters (default #{OKF::Bundle::Linter::DEFAULT_MIN_BODY})") { |v| options[:min_body] = v }
-          o.on("--stale-after DUR", "flag concepts older than DUR (e.g. 90d, 12w, 2026-01-01)") { |v| options[:stale_after] = v }
+          o.on("--stale-after DUR", "flag concepts older than DUR (e.g. 90d, 12w, 2026-01-01,",
+            "or a full 2026-01-01T09:00:00Z timestamp)") { |v| options[:stale_after] = v }
+          o.on("--today DATE", "the day `expired` compares stale_after against (default: today)") { |v| options[:today] = v }
           o.on("--only LIST", Array, "run only these checks (comma-separated)") { |v| options[:only] = v.map(&:to_sym) }
           o.on("--except LIST", Array, "skip these checks (comma-separated)") { |v| options[:except] = v.map(&:to_sym) }
-          o.on("--fail-on LEVEL", %w[never warn], "exit 1 when a finding at LEVEL exists (never | warn)") { |v| options[:fail_on] = v.to_sym }
+          o.on("--fail-on LEVEL", %w[never info warn], "exit 1 when a finding at LEVEL exists (never | info | warn)") { |v| options[:fail_on] = v.to_sym }
           help_flag(o)
         end
         dir = positional_dir(parser, argv) or return 2
@@ -56,15 +67,42 @@ module OKF
           return 2
         end
 
+        today = parse_today(options[:today])
+        if today == :invalid
+          @err.puts "error: invalid --today `#{options[:today]}` (use YYYY-MM-DD)"
+          return 2
+        end
+
         folder = OKF::Bundle::Folder.load(dir)
-        report = folder.lint(min_body: options[:min_body], stale_before: stale_before, only: options[:only], except: options[:except])
+        report = folder.lint(min_body: options[:min_body], stale_before: stale_before, today: today,
+          only: options[:only], except: options[:except])
         note_skipped(report.stats[:skipped])
         options[:json] ? print_lint_json(dir, report) : print_lint(dir, report)
-        options[:fail_on] == :warn && report.warnings.any? ? 1 : 0
+        lint_exit(options[:fail_on], report)
       end
 
       private
 
+      def lint_exit(fail_on, report)
+        case fail_on
+        when :warn then report.warnings.any? ? 1 : 0
+        when :info then report.findings.any? ? 1 : 0
+        else 0
+        end
+      end
+
+      # The CLI always supplies a clock — Date.today unless --today pins one —
+      # so `okf lint` reports `expired` out of the box while the pure library
+      # default runs no clock check at all (and confesses via skipped_checks).
+      def parse_today(value)
+        return Date.today if value.nil?
+        return :invalid unless value.match?(Concept::ISO_DATE)
+
+        Date.iso8601(value)
+      rescue ArgumentError
+        :invalid
+      end
+
       # Turn a --stale-after value (90d, 12w, or an ISO date) into an absolute cutoff
       # Time so the pure Linter never reads the clock. nil when unset, :invalid on a
       # bad value.
@@ -74,8 +112,14 @@ module OKF
         if (match = value.match(/\A(\d+)([dw])\z/))
           days = match[1].to_i * (match[2] == "w" ? 7 : 1)
           Time.now - (days * 86_400)
-        else
+        elsif value.match?(Concept::ISO_CUTOFF)
+          # Not --today's grammar: that one is a calendar day, this one a
+          # moment, so a full `generated.at` timestamp is accepted and reduced
+          # to its date. What both refuse is the same — the basic and week
+          # spellings Date.iso8601 would silently reinterpret.
           Date.iso8601(value).to_time
+        else
+          :invalid
         end
       rescue ArgumentError
         :invalid
@@ -87,6 +131,8 @@ module OKF
         @out.puts "  concepts: #{stats[:concepts]}   edges: #{stats[:edges]}   index.md: #{stats[:indexes]}   log.md: #{stats[:logs]}"
         summary = lint_summary(stats)
         @out.puts "  #{summary}" unless summary.empty?
+        posture = lint_posture(stats)
+        @out.puts "  #{posture}" unless posture.empty?
 
         LINT_CATEGORIES.each do |name, checks|
           findings = report.findings.select { |finding| checks.include?(finding[:check]) }
@@ -99,6 +145,8 @@ module OKF
           end
         end
 
+        skipped = Array(report.stats[:skipped_checks])
+        @out.puts "  skipped: #{skipped.join(", ")} (no clock or cutoff supplied)" unless skipped.empty?
         @out.puts
         @out.puts "  #{lint_verdict(report)}"
       end
@@ -120,6 +168,16 @@ module OKF
         parts.join("   ")
       end
 
+      # The bundle's trust/status posture, printed only when there is a bundle
+      # to have one (an empty bundle has no distribution worth a line).
+      def lint_posture(stats)
+        return "" if stats[:concepts].zero?
+
+        trust = stats[:trust].map { |tier, count| "#{tier} #{count}" }.join(", ")
+        status = stats[:status].map { |value, count| "#{value} #{count}" }.join(", ")
+        "trust: #{trust}   status: #{status}"
+      end
+
       def lint_glyph(finding)
         finding[:severity] == :warn ? paint("! warn", 33) : "· info"
       end

data/lib/okf/cli/references.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+module OKF
+  class CLI
+    # The §6.3 inventory: every file under `references/`, which concepts cite
+    # it through the §6.2 path-valued fields, and the pointers into
+    # `references/` that resolve to nothing — with the leading-slash fix named
+    # when a bare path written from a subdirectory is what missed. An advisory
+    # read (exit 0): what a curator acts on lives in the output, never the
+    # status.
+    class References < Command
+      def self.id
+        :references
+      end
+
+      def self.group
+        :read
+      end
+
+      def self.help_rows
+        [
+          [ "references <dir|@slug> [--json]", "inventory references/ files and the concepts citing them" ]
+        ]
+      end
+
+      def call(argv)
+        options = { json: false }
+        parser = OptionParser.new do |o|
+          o.banner = "Usage: okf references <dir|@slug> [--json]"
+          json_flags(o, options, "emit the inventory as JSON")
+          projection_flags(o, options)
+          help_flag(o)
+        end
+        dir = positional_dir(parser, argv) or return 2
+
+        folder = OKF::Bundle::Folder.load(dir)
+        report_skipped(folder)
+        references = folder.references
+        return print_references_json(dir, references, options) if options[:json]
+
+        print_references(dir, references)
+        0
+      end
+
+      private
+
+      def print_references(dir, references)
+        entries = references.entries
+        @out.puts "References — #{bundle_label(dir)} (#{entries.size} #{pluralize(entries.size, "file")})"
+        @out.puts "  (none)" if entries.empty?
+        entries.group_by { |entry| entry[:dir] }.sort_by(&:first).each do |folder, group|
+          width = group.map { |entry| File.basename(entry[:path]).length }.max
+          @out.puts
+          @out.puts "  #{folder}/"
+          group.each do |entry|
+            @out.puts "    #{File.basename(entry[:path]).ljust(width)}  #{entry_note(entry)}"
+          end
+        end
+        print_dangling(references.dangling)
+      end
+
+      def entry_note(entry)
+        marker = entry[:kind] == "concept" ? "[concept]  " : ""
+        cited = entry[:referenced_by]
+        return "#{marker}(unreferenced)" if cited.empty?
+
+        "#{marker}← #{cited.map { |ref| "#{ref[:id]} (#{ref[:field]})" }.join(", ")}"
+      end
+
+      def print_dangling(rows)
+        return if rows.empty?
+
+        @out.puts
+        @out.puts "  dangling pointers:"
+        rows.each do |row|
+          @out.puts "    #{row[:id]} — #{row[:field]}: #{row[:raw]}"
+          line = "      resolves to #{row[:resolved]}, which does not exist"
+          # hint is only ever the leading-slash fix, so the human line can name
+          # the spelling that would have hit without restating the sentence.
+          line += " — /#{row[:raw]} does (missing leading slash?)" if row[:hint]
+          @out.puts line
+        end
+      end
+
+      def print_references_json(dir, references, options)
+        rows = references.entries.map do |entry|
+          { "path" => entry[:path], "dir" => entry[:dir], "kind" => entry[:kind],
+            "referenced_by" => entry[:referenced_by].map { |ref| stringify(ref) } }
+        end
+        dangling = references.dangling.map { |row| stringify(row) }
+        emit_list_json(dir, "references", rows, options, "dangling" => dangling)
+      end
+    end
+
+    register(References)
+  end
+end

data/lib/okf/cli/search.rb

@@ -34,7 +34,8 @@ module OKF
       def call(argv)
         options = { json: false, regexp: false, fuzzy: false, engine: nil }
         parser = OptionParser.new do |o|
-          o.banner = "Usage: okf search <dir|@slug…|@all> <term…> [--engine NAME] [--regexp|--fuzzy] [--in FIELDS] [--type T] [--dir D] [--tag T] [--json]"
+          o.banner = "Usage: okf search <dir|@slug…|@all> <term…> [--engine NAME] [--regexp|--fuzzy] " \
+                     "[--in FIELDS] [--type T] [--dir D] [--tag T] [--status S] [--trust T] [--json]"
           search_engine_note(o)
           json_flags(o, options, "emit the matches as JSON")
           projection_flags(o, options)
@@ -209,16 +210,30 @@ module OKF
       #
       # Filters stay per-bundle — they are per-folder questions — so they apply to
       # the merged rows by (slug, id) afterwards.
+      #
+      # The one thing that is *not* a per-folder question is what `--dir root`
+      # means. The alias yields to a directory that really carries the name, so
+      # resolving it inside this loop made one flag mean two things in one
+      # ranking: the `root/` subtree where a bundle has one, the bundle root
+      # where it does not, merged with nothing in the output saying so. The
+      # served set answers it once, and a bundle without the directory then
+      # matches nothing — which is what `--dir` already does everywhere for a
+      # directory a bundle lacks.
       def multi_search(pairs, terms, options)
-        bundles = []
-        keeps = {}
-        total = 0
-        pairs.each do |slug, dir|
+        folders = pairs.map do |slug, dir|
           folder = OKF::Bundle::Folder.load(dir)
           report_skipped(folder)
-          total += folder.bundle.concepts.size
-          bundles << [ slug, folder.bundle ]
-          keep = filter_ids(folder, options)
+          [ slug, folder ]
+        end
+        total = folders.reduce(0) { |sum, (_, folder)| sum + folder.bundle.concepts.size }
+        bundles = folders.map { |slug, folder| [ slug, folder.bundle ] }
+        # The served set's directories, only when a flag will consult them —
+        # the alias is resolved once across the whole run (see filter_ids),
+        # and an unfiltered search never pays the walk.
+        dirs = options[:dir] || options[:area] ? folders.flat_map { |_, folder| folder.directories }.uniq : nil
+        keeps = {}
+        folders.each do |slug, folder|
+          keep = filter_ids(folder, options, dirs)
           keeps[slug] = keep unless keep.nil?
         end
         rows = OKF::Bundle::Search.across(bundles, terms, fields: options[:in], regexp: options[:regexp],

data/lib/okf/cli/stats.rb

@@ -29,51 +29,15 @@ module OKF
 
         folder = OKF::Bundle::Folder.load(dir)
         report_skipped(folder)
-        stats = bundle_stats(folder)
+        stats = folder.stats
         options[:json] ? print_stats_json(dir, stats) : print_stats(dir, stats)
         0
       end
 
       private
 
-      # Bundle-level rollups derived from the catalog and the graph indexes.
-      def bundle_stats(folder)
-        graph = folder.graph(minimal: true)
-        entries = folder.catalog
-        by_type = graph.type_index.transform_values(&:size).sort_by { |_, n| -n }.to_h
-        by_top_dir = entries.group_by { |entry| entry[:top_dir] }.transform_values(&:size).sort_by { |_, n| -n }.to_h
-        by_dir = directory_counts(folder)
-        {
-          concepts: entries.size,
-          dirs: by_dir.size,
-          top_dirs: by_top_dir.size,
-          types: by_type.size,
-          cross_links: graph.edges.size,
-          tags: graph.tag_index.size,
-          by_type: by_type,
-          by_dir: by_dir,
-          by_top_dir: by_top_dir
-        }
-      end
-
-      # Every directory the bundle has, with the concepts that live *directly* in
-      # it. Read off Bundle#directory_index — the same map `okf dirs` lists and
-      # `--dir` is answered against — rather than off the catalog, which knows
-      # only the directories that happen to hold a concept. Grouping the catalog
-      # made `stats` and `dirs` report different totals for one bundle, and left
-      # an addressable directory out of by_dir entirely: `--dir deeply` answers,
-      # but nothing in `stats` said `deeply` was there to ask about.
-      #
-      # A directory holding nothing directly therefore appears at 0. That is the
-      # honest reading — it is the same zero `okf dirs` prints in its Concepts
-      # column — and it keeps `dirs` equal to `by_dir.size`. Ties break by path so
-      # the order is total, not whatever the sort happened to leave.
-      def directory_counts(folder)
-        folder.directory_index
-              .map { |entry| [ entry[:dir], entry[:count] ] }
-              .sort_by { |dir, count| [ -count, dir ] }.to_h
-      end
-
+      # The rollup itself is Bundle#stats — one home, shared with the MCP
+      # shell, after the by_dir subtlety diverged once when hand-copied.
       def print_stats(dir, stats)
         @out.puts "Stats — #{bundle_label(dir)}"
         @out.puts

data/lib/okf/cli/tags.rb

@@ -23,7 +23,7 @@ module OKF
       def call(argv)
         options = { json: false, by: nil }
         parser = OptionParser.new do |o|
-          o.banner = "Usage: okf tags <dir|@slug> [--by type|dir] [--type T] [--dir D] [--json]"
+          o.banner = "Usage: okf tags <dir|@slug> [--by type|dir] [--type T] [--dir D] [--status S] [--trust T] [--json]"
           json_flags(o, options, "emit the tag index as JSON")
           o.on("--by DIM", %w[type dir area], "group the tags by a concept dimension (type | dir)") do |v|
             options[:by] = v.to_sym
@@ -50,52 +50,15 @@ module OKF
         report_skipped(folder)
         graph = folder.graph(minimal: true)
         titles = graph.nodes.map { |node| [ node[:id], node[:title] ] }.to_h
-        groups = tag_groups(graph.tag_index, folder, options)
+        groups = folder.tag_groups(by: options[:by],
+          entries: filter_entries(folder.catalog, options, dir_scope(folder, options)))
         options[:json] ? print_grouped_tags_json(dir, options[:by], groups) : print_grouped_tags(dir, options[:by], groups, titles)
         0
       end
 
-      # [ [ group, rows ], … ] — groups sorted by name, rows shaped like index_rows'
-      # plus each tag's total across the narrowed set. A tag carried in several
-      # groups appears in each, counted per group; count/total per row is what
-      # makes a tag's spread — local to one group, or cutting across several —
-      # readable without cross-referencing the groups by hand.
-      def tag_groups(tag_index, folder, options)
-        by_id = filter_entries(folder.catalog, options).map { |entry| [ entry[:id], entry ] }.to_h
-        groups = {}
-        totals = Hash.new(0)
-        tag_index.each do |tag, ids|
-          ids.each do |id|
-            entry = by_id[id]
-            next if entry.nil?
-
-            key = group_key(entry, options[:by])
-            ((groups[key] ||= {})[tag] ||= []) << id
-            totals[tag] += 1
-          end
-        end
-        groups.map do |key, tags|
-          rows = tags.map { |tag, ids| { tag: tag, count: ids.length, total: totals[tag], concepts: ids } }
-                     .sort_by { |row| [ -row[:count], row[:tag] ] }
-          [ key, rows ]
-        end.sort_by(&:first)
-      end
-
-      # A catalog entry's type for display — "Untyped" when blank, matching the graph.
-      def entry_type(entry)
-        OKF.blank?(entry[:type]) ? "Untyped" : entry[:type]
-      end
-
-      # The group a concept falls in, in its *stored* spelling — `.` for the root
-      # under --by dir, never "(root)". The human label is applied at print time,
-      # so the JSON and the table cannot disagree about which one is the data.
-      def group_key(entry, dim)
-        case dim
-        when :type then entry_type(entry)
-        when :dir then entry[:dir]
-        else entry[:top_dir]
-        end
-      end
+      # The grouping itself is Bundle#tag_groups — one home, shared with the
+      # MCP shell; this layer keeps only what is the CLI's own, the filter
+      # narrowing passed through `entries:`.
 
       # `.` prints "(root)" bare; every other dir carries the trailing slash that
       # says it is one. The deprecated --by area already stores "(root)" itself.

data/lib/okf/cli/types.rb

@@ -21,7 +21,7 @@ module OKF
       def call(argv)
         options = { json: false }
         parser = OptionParser.new do |o|
-          o.banner = "Usage: okf types <dir|@slug> [--dir D] [--tag T] [--json]"
+          o.banner = "Usage: okf types <dir|@slug> [--dir D] [--tag T] [--status S] [--trust T] [--json]"
           json_flags(o, options, "emit the type index as JSON")
           filter_flags(o, options, :area, :tag)
           help_flag(o)