featureparity 0.0.28 → 0.0.29

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: dd6b0a540d21e123a2ceb43cb9f23005c218319866ff7e079b951d6288199bb1
-  data.tar.gz: 6e0d61e3a3d9e6f590c6e978b134736877b5abc8da2a9a80332ff6cd203dbf58
+  metadata.gz: 5cef61c9093573a494f9d27b203554e51dfc2f0a6d60ae43e666564c8e2b1740
+  data.tar.gz: 7162500244354be8c93a78499e479ac30a7df2d25ab4f818ce3451a6819ce960
 SHA512:
-  metadata.gz: fe1d8110555996bc72c885d502139e6f18dbef1d2ee8b8623eaf48c74dce6c40b33f46ffe4b42f09c9f92570380abab9b4dff77df3520d300ec6f43f35214890
-  data.tar.gz: 1f95d64e43e62a63411bd8cc665248777c3acdc58795e16552d4b5f671d3a1fb89a774bbf066e5f65f55bba7b716cc5f2fa78d51ea2b1a5afdc1fcd547acfa2d
+  metadata.gz: a4733078f1af140723dadb54a0ed5e3ba5c80b771a48ba9f8364c6dcfb088cb9e3c39c79fac27b0fd5083e2339e47b8b6fb76fe5c54fde772f68fdbc2a005e7d
+  data.tar.gz: 21330096e2f61cf6100dc54708c25818647f88581e0d0ef073bc84b2ec532556582012d899a663a0e96ce9e757ff6f5ae0ec51338be797bc19363f40e97d86af

data/lib/fp/cli.rb

@@ -8,6 +8,8 @@ module Fp
     COMMANDS = {
       'init' => Commands::Init,
       'tutorial' => Commands::Tutorial,
+      'doctor' => Commands::Doctor,
+      'run' => Commands::Run,
       'projects' => Commands::Projects,
       'surfaces' => Commands::Surfaces,
       'showroom' => Commands::Showroom,
@@ -15,7 +17,10 @@ module Fp
       'show' => Commands::Show,
       'propose' => Commands::Propose,
       'propose-change' => Commands::ProposeChange,
+      'mark' => Commands::Mark,
       'comment' => Commands::Comment,
+      'question' => Commands::Question,
+      'questions' => Commands::Questions,
       'comments' => Commands::Comments,
       'history' => Commands::History,
       'analyze' => Commands::Analyze,
@@ -25,6 +30,7 @@ module Fp
       'changed-tests' => Commands::ChangedTests,
       'spot-check' => Commands::SpotCheck,
       'check' => Commands::Check,
+      'coverage' => Commands::Coverage,
       'matrix' => Commands::Matrix,
       'export' => Commands::Export,
       'profile' => Commands::Profile,
@@ -42,6 +48,9 @@ module Fp
     class << self
       def run(argv)
         args = argv.dup
+        # Everything after `--` belongs to another program (`fp run -- pytest -p no:cov`),
+        # so global flags and --help are only looked for before it.
+        passthrough = (split = args.index('--')) ? args.slice!(split..) : []
         global_opts = extract_global_options(args)
 
         command_name = args.shift || 'help'
@@ -71,7 +80,7 @@ module Fp
 
         # Profile/config commands don't need auth. `init` is here too: it only writes
         # files into the repo, and onboarding a repo must work before anyone has a key.
-        needs_auth = !%w[init profile config repos setup whoami version help].include?(command_name)
+        needs_auth = !%w[init doctor profile config repos setup whoami version help mark].include?(command_name)
 
         if needs_auth
           config = Config.new(profile: global_opts[:profile], api_url: global_opts[:api_url])
@@ -87,7 +96,7 @@ module Fp
 
         output = Output.new(json: global_opts[:json])
         command = command_class.new(client: client, output: output, config: config)
-        command.run(args)
+        command.run(args + passthrough)
       rescue Interrupt
         warn "\nAborted."
         exit 130

data/lib/fp/client.rb

@@ -247,6 +247,21 @@ module Fp
       post("/api/requirements/#{requirement_id}/changes/#{change_id}/comment", params)
     end
 
+    # GET /requirements/:id/questions
+    #
+    # The questions left for a human on a requirement (Fizzy #1786), open and resolved.
+    def list_requirement_questions(requirement_id)
+      get("/api/requirements/#{requirement_id}/questions")
+    end
+
+    # POST /requirements/:id/questions
+    #
+    # Attach an open question for a human to a draft (or active) requirement. There is
+    # no resolve method: only a human answers or dismisses, from the web app.
+    def ask_requirement_question(requirement_id, text)
+      post("/api/requirements/#{requirement_id}/questions", { text: text })
+    end
+
     # GET /requirements/:id/comments
     #
     # The team's comments on a requirement, oldest first, plus who can be tagged:
@@ -367,6 +382,17 @@ module Fp
       get("/api/projects/#{project_id}/parity", params)
     end
 
+    # GET /projects/:project_id/parity?include_drafts=true — the same report plus a
+    # top-level `drafts` array: never-approved drafts with their cells resolved from
+    # evidence. Informational only; the server never gates on it (Fizzy #1786). Read by
+    # `fp coverage`, `fp list --status draft --gaps` and `fp check --include-drafts`.
+    def get_parity_with_drafts(project_id, level: nil, surface: nil)
+      params = { include_drafts: 'true' }
+      params[:level] = level if level
+      params[:surface] = surface if surface
+      get("/api/projects/#{project_id}/parity", params)
+    end
+
     # POST /projects/:project_id/parity/preview — the pull-request gate.
     #
     # Evaluates JUnit results as an overlay on the stored grid *without persisting them*,

data/lib/fp/commands/base.rb

@@ -210,6 +210,20 @@ module Fp
         project['id']
       end
 
+      # One line on stderr before a command writes to a project, when the API it's about
+      # to write to isn't production. FP_PROFILE / FP_API_URL left over in a shell put an
+      # agent's new project on a dev environment with nothing to say so (Fizzy #1786).
+      # Stderr keeps --json output parseable; it never stops the command.
+      def warn_if_not_production!
+        env = config&.environment
+        return if env.nil? || env == 'production'
+
+        profile = config.profile_name
+        via = profile ? " (profile '#{profile}')" : ''
+        $stderr.puts "⚠ Writing to the '#{env}' environment at #{config.api_url}#{via}, not production. " \
+                     'Run `fp whoami` to see where that comes from.'
+      end
+
       def require_flag(opts, flag, message = nil)
         unless opts[flag]
           message ||= "--#{flag.to_s.tr('_', '-')} is required"

data/lib/fp/commands/check.rb

@@ -51,15 +51,17 @@ module Fp
       help_flag :surface, 'Gate a single surface'
       help_flag :test_type, 'Gate a single test type'
       help_flag :level, 'Override the enforcement level for this run (off/regression/covered/strict)'
-      help_flag :junit, "Gate the branch on this run's results, overlaid on the grid (repeatable, one per surface)"
+      help_flag :junit, "Gate the branch on this run's results (JUnit XML or RSpec JSON), overlaid on the grid (repeatable, one per surface)"
       help_flag :base_dir, "Where the report's relative test-file paths resolve from"
       help_flag :pr, 'With --junit: this run is a pull request — fail only on parity it makes worse, ' \
                      'not on what the default branch already owes (optionally the PR URL)'
       help_flag :warn_only, 'Report violations but still exit 0'
+      help_flag :include_drafts, 'Also show draft coverage after the verdict (never changes the exit code)'
       help_example 'fp check', 'Gate on recorded state (project from .featureparity.yml)'
       help_example 'fp check --surface api --junit junit.xml', 'Gate a default-branch run on its own results'
       help_example 'fp check --surface api --junit junit.xml --pr', 'Gate a pull request on what it changes'
       help_example 'fp check --warn-only --json'
+      help_example 'fp check --include-drafts', 'Onboarding: which drafts have evidence, which have none'
       help_note "Exit 0 = passed, 1 = violations (or request failed). The level lives on the project\n" \
                 'server-side; --level only overrides this one run.'
 
@@ -73,7 +75,8 @@ module Fp
         # `--pr` alone is true; `--pr <url>` carries the URL. Not :boolean on purpose, so
         # the parser takes a following value when one is given.
         pr: :string,
-        warn_only: :boolean
+        warn_only: :boolean,
+        include_drafts: :boolean
       }.freeze
 
       # How many inherited violations to list before summarising the rest. They are
@@ -103,7 +106,9 @@ module Fp
         project_id = resolve_project_id(project_slug)
 
         result =
-          if junit_paths.empty?
+          if junit_paths.empty? && opts[:include_drafts]
+            client.get_parity_with_drafts(project_id, level: level, surface: surface)
+          elsif junit_paths.empty?
             client.get_parity(project_id, level: level, surface: surface)
           else
             preview(project_id, junit_paths, surface, level, opts)
@@ -125,7 +130,12 @@ module Fp
                'this verdict counts every violation, including those the default branch already has.'
         end
 
+        # Draft coverage rides along when asked for. Informational only: it is added after
+        # the verdict was decided and never feeds `passed` (Fizzy #1786).
+        report = report.merge('drafts' => draft_rows(project_id, level, surface, report)) if opts[:include_drafts]
+
         render(report, violations, passed, project_slug, opts)
+        print_drafts(report) if opts[:include_drafts] && !output.json?
 
         # A failing gate is the whole point of the command, so it must be the exit code
         # and not just something printed. --warn-only downgrades it to advisory.
@@ -134,6 +144,30 @@ module Fp
 
       private
 
+      # The standing read already carries `drafts` when asked for. The preview endpoint
+      # doesn't, so a --junit run reads them from the standing report instead; drafts are
+      # recorded state either way. A failed or too-old read is a warning, never a failed
+      # gate, because drafts can't change the verdict.
+      def draft_rows(project_id, level, surface, report)
+        return report['drafts'] if report.key?('drafts')
+
+        result = client.get_parity_with_drafts(project_id, level: level, surface: surface)
+        drafts = result[:ok] ? (result[:data]['parity'] || {})['drafts'] : nil
+        if drafts.nil?
+          warn 'Warning: draft coverage is unavailable from this API; the verdict is unaffected.'
+          return []
+        end
+        drafts
+      end
+
+      def print_drafts(report)
+        drafts = report['drafts'] || []
+        puts
+        puts "Draft coverage (#{drafts.size} draft(s), not gated):"
+        Coverage.print_drafts(output, drafts, report['surfaces'] || [])
+        Coverage.print_untested(Coverage.untested(drafts)) unless drafts.empty?
+      end
+
       # Preview mode needs to know which surface the results belong to, because the
       # server uses it to decide which cells the run had a chance to cover — and
       # therefore which vanished tests it may legitimately flag.
@@ -162,7 +196,7 @@ module Fp
         client.preview_parity(
           project_id,
           surface: surface,
-          junit_xmls: junit_paths.map { |p| File.read(p) },
+          junit_xmls: junit_paths.map { |p| Fp::JUnit.read_xml(p) },
           level: level,
           results: resolve_results(junit_paths, surface, opts),
           pull_request: !!opts[:pr],

data/lib/fp/commands/ci_report.rb

@@ -57,7 +57,7 @@ module Fp
       help_flag :test_type, 'Default test kind for markers that pin none'
       help_flag :ci_url, 'CI run URL to record on the evidence'
       help_flag :pr, "Mark this as a PR's CI: passing tests recorded as pr_passing, no merged evidence demoted"
-      help_flag :junit, 'JUnit XML report (repeatable to combine a surface split across shards)'
+      help_flag :junit, 'JUnit XML report, or RSpec `--format json` output (repeatable to combine a surface split across shards)'
       help_flag :base_dir, "Where the report's relative test-file paths resolve from (e.g. frontend)"
       help_flag :repo, 'Repository the tests live in (org/repo)'
       help_flag :sha, 'Checkout commit SHA'
@@ -127,7 +127,7 @@ module Fp
           totals[:unmarked_failures].concat(resolved[:unmarked_failures])
           totals[:test_revisions] += test_revisions.length
 
-          { path: path, xml: File.read(path), results: results, test_revisions: test_revisions }
+          { path: path, xml: Fp::JUnit.read_xml(path), results: results, test_revisions: test_revisions }
         end
 
         # One surface run may be split across several reports (unit + e2e, shards, etc.).

data/lib/fp/commands/comment.rb

@@ -17,7 +17,7 @@ module Fp
         source_type: :string, source_url: :string, source_context: :string
       }.freeze
 
-      VALID_SOURCE_TYPES = %w[fizzy discord github_issue jira notion manual ai_chat].freeze
+      VALID_SOURCE_TYPES = %w[fizzy discord github_issue jira notion manual ai_chat repo_scan].freeze
 
       help_summary "Comment on a requirement's open change proposal"
       help_usage 'fp comment <slug> --body "..." --project <slug>'

data/lib/fp/commands/coverage.rb

@@ -0,0 +1,149 @@
+# frozen_string_literal: true
+
+module Fp
+  module Commands
+    # fp coverage [--project X] [--surface api] [--all] [--json]
+    #
+    # Draft coverage: which draft requirements have marked tests or evidence on which
+    # surfaces, and which have none.
+    #
+    # The gate measures active requirements only (plus ones an open proposal demoted), so
+    # on a freshly onboarded project — where every requirement is still a draft — `fp
+    # check` says "Nothing to enforce yet" and `fp list --gaps` says "No gaps found". The
+    # agent that just proposed the catalog and marked the tests had no way to confirm its
+    # work, and nothing to hand the human but "trust me" (Fizzy #1786). This reads the
+    # parity report's `drafts` section, where the server resolves each draft's cells from
+    # evidence exactly as it would once the draft is active.
+    #
+    # It ends with a plain list of drafts that have no evidence on a required surface —
+    # the "requirements with no test" section an onboarding agent hands the human.
+    #
+    # Informational only. Drafts are reported, never gated; this command always exits 0
+    # on a successful read.
+    class Coverage < Base
+      help_summary 'Show which draft requirements have evidence on which surfaces (never gated)'
+      help_usage 'fp coverage [--project <slug>] [--surface X] [--all]'
+      help_flag :project, 'Project slug (falls back to .featureparity.yml)'
+      help_flag :surface, 'Limit to one surface'
+      help_flag :all, 'Also list the measured requirements (active, or under review) the gate checks'
+      help_example 'fp coverage', 'Drafts × surfaces, then the drafts with no evidence'
+      help_example 'fp coverage --all --json'
+      help_note "Drafts are not enforced: a human activates a draft before fp check gates on it.\n" \
+                'A cell reads the same here as it will in the matrix once the draft is active.'
+
+      KNOWN_FLAGS = {
+        project: :string,
+        surface: :string,
+        all: :boolean
+      }.freeze
+
+      def run(args)
+        opts, = parse_flags(args, KNOWN_FLAGS)
+        project_config = ProjectConfig.discover
+        project_slug = require_project!(opts, project_config)
+        project_id = resolve_project_id(project_slug)
+        surface = opts[:surface] || project_config.surface
+
+        result = client.get_parity_with_drafts(project_id, surface: surface)
+        unless result[:ok]
+          output.error(result[:error], status: result[:status])
+          exit 1
+        end
+
+        report = result[:data]['parity'] || {}
+        unless report.key?('drafts')
+          output.error('This FeatureParity API does not report draft coverage yet (it predates ' \
+                       '`include_drafts`). Nothing was checked.')
+          exit 1
+        end
+
+        render(report, project_slug, surface, all: opts[:all])
+      end
+
+      # Drafts with no evidence on at least one required surface, as
+      # [{ 'slug', 'title', 'surfaces' => [...] }]. "No evidence" is the `missing` state:
+      # nothing — not even a stub or a red test — is filed for that surface.
+      def self.untested(drafts)
+        Array(drafts).filter_map do |row|
+          bare = Array(row['cells']).select { |c| c['state'] == 'missing' }.map { |c| c['surface'] }
+          next if bare.empty?
+
+          { 'slug' => row['slug'], 'title' => row['title'], 'surfaces' => bare }
+        end
+      end
+
+      # The drafts × surfaces table plus the "no evidence" list, for text output. Shared
+      # with `fp check --include-drafts`, so the two can't describe drafts differently.
+      def self.print_drafts(output, rows, surfaces, show_status: false)
+        if rows.empty?
+          puts 'No draft requirements.'
+          return
+        end
+
+        headers = %w[SLUG]
+        headers << 'STATUS' if show_status
+        headers += surfaces
+        table = rows.map do |row|
+          by_surface = Array(row['cells']).to_h { |c| [c['surface'], c['state']] }
+          cells = surfaces.map { |key| by_surface.key?(key) ? Parity.glyph(by_surface[key]) : Parity::NOT_REQUIRED }
+          line = [row['slug']]
+          line << row['status'] if show_status
+          line + cells
+        end
+        output.table(headers, table)
+        puts Parity::LEGEND
+      end
+
+      def self.print_untested(untested)
+        puts
+        if untested.empty?
+          puts 'Every draft has evidence on each of its required surfaces.'
+          return
+        end
+
+        puts "#{untested.size} draft(s) with no evidence on a required surface:"
+        untested.each { |u| puts "  #{u['slug']} — no evidence on: #{u['surfaces'].join(', ')}" }
+      end
+
+      private
+
+      def render(report, project_slug, surface, all:)
+        drafts = report['drafts'] || []
+        surfaces = report['surfaces'] || []
+        untested = self.class.untested(drafts)
+
+        payload = {
+          'project' => project_slug,
+          'surface' => surface,
+          'surfaces' => surfaces,
+          'drafts' => drafts,
+          'untested' => untested
+        }
+        payload['measured'] = report['requirements'] || [] if all
+
+        output.success(payload) do
+          scope = surface ? " (surface: #{surface})" : ''
+          puts "Draft coverage: #{project_slug}#{scope}"
+          puts
+
+          if all
+            measured = report['requirements'] || []
+            puts "Measured by the gate (#{measured.size}):"
+            if measured.empty?
+              puts 'None — no requirement is active yet.'
+            else
+              self.class.print_drafts(output, measured, surfaces, show_status: true)
+            end
+            puts
+            puts "Drafts (#{drafts.size}):"
+          end
+
+          self.class.print_drafts(output, drafts, surfaces)
+          self.class.print_untested(untested) unless drafts.empty?
+          puts
+          puts 'Drafts are reported, never gated. A human activates a draft before fp check enforces it.'
+        end
+      end
+    end
+  end
+end

data/lib/fp/commands/doctor.rb

@@ -0,0 +1,228 @@
+# frozen_string_literal: true
+
+require 'rbconfig'
+
+module Fp
+  module Commands
+    # fp doctor [--dir PATH] [--json]
+    #
+    # Says whether fp will work here, and what this repo needs before its tests can report
+    # (Fizzy #1786). Purely local: no API calls, no key needed.
+    #
+    #   Ruby     which Ruby is running fp, where the gem lives, and whether this directory
+    #            pins a different Ruby (.ruby-version, .tool-versions, mise.toml). A
+    #            version-manager shim resolves `fp` against the *pinned* Ruby, so a gem
+    #            installed under another one fails inside the repo with
+    #            `mise ERROR No version is set for shim: fp` and works from /tmp.
+    #   Config   the API environment (warning off production), whether a key resolved,
+    #            and which .featureparity.yml applies.
+    #   Repo     RepoDetector's summary: test runners and the command that makes each emit
+    #            a report, suggested surfaces, database and devcontainer.
+    #
+    # The shim error itself happens before fp starts, so doctor can only catch it when fp
+    # is reached some other way (another Ruby's bin dir, from /tmp). The skill and the
+    # generated AGENTS.md section describe that case for the agent that hits it.
+    class Doctor < Base
+      help_summary 'Check that fp works here: Ruby and version-manager pins, config, and what the repo needs'
+      help_usage 'fp doctor [--dir PATH]'
+      help_flag :dir, 'Directory to check (defaults to the working directory)'
+      help_example 'fp doctor'
+      help_example 'fp doctor --json', 'Machine-readable, for an agent to act on'
+      help_note "Purely local; makes no API calls, so it works without a key.\n" \
+                "If `fp` itself fails with `mise ERROR No version is set for shim: fp`, the shim stopped it\n" \
+                'before fp could run: install the gem under the pinned Ruby (`gem install featureparity` in the repo).'
+
+      KNOWN_FLAGS = { dir: :string }.freeze
+
+      # Nearest file wins, and within one directory mise's own precedence applies.
+      PIN_FILES = %w[mise.toml .mise.toml .tool-versions .ruby-version].freeze
+
+      def run(args)
+        opts, = parse_flags(args, KNOWN_FLAGS)
+        dir = File.expand_path(opts[:dir] || Dir.pwd)
+        unless File.directory?(dir)
+          output.error("Not a directory: #{dir}")
+          exit 1
+        end
+
+        report = {
+          ruby: ruby_report(dir),
+          config: config_report(dir),
+          repo: RepoDetector.new(repo_root(dir)).detect
+        }
+        report[:agents_section] = agents_section_report(repo_root(dir))
+
+        output.success(report) { print_report(report) }
+      end
+
+      # The nearest Ruby pin at or above dir: { version:, file:, manager: } or nil.
+      def self.ruby_pin(dir)
+        current = File.expand_path(dir)
+        loop do
+          PIN_FILES.each do |name|
+            file = File.join(current, name)
+            next unless File.file?(file)
+
+            version = parse_pin(file)
+            return { version: version, file: file, manager: manager_for(name) } if version
+          end
+          parent = File.dirname(current)
+          return nil if parent == current
+
+          current = parent
+        end
+      end
+
+      def self.parse_pin(file)
+        text = File.read(file)
+        raw = case File.basename(file)
+              when '.ruby-version' then text.lines.first.to_s.strip
+              when '.tool-versions' then text[/^\s*ruby\s+(\S+)/, 1]
+              else text[/^\s*ruby\s*=\s*(?:\[\s*)?(?:\{[^}]*?version\s*=\s*)?["']([^"']+)["']/, 1]
+              end
+        raw = raw.to_s.sub(/\Aruby-/, '').strip
+        raw.empty? ? nil : raw
+      rescue SystemCallError
+        nil
+      end
+
+      def self.manager_for(name)
+        case name
+        when 'mise.toml', '.mise.toml' then 'mise'
+        when '.tool-versions' then 'mise or asdf'
+        else 'mise, rbenv, chruby or asdf'
+        end
+      end
+
+      # "3.4" pins any 3.4.x; "latest"/"system" pin nothing we can check.
+      def self.version_matches?(pinned, running)
+        return true unless pinned.match?(/\A\d+(\.\d+)*\z/)
+
+        running.split('.').first(pinned.split('.').length) == pinned.split('.')
+      end
+
+      private
+
+      def repo_root(dir)
+        found = ProjectConfig.find_file(dir)
+        found ? File.dirname(found) : dir
+      end
+
+      def ruby_report(dir)
+        running = RUBY_VERSION
+        pin = self.class.ruby_pin(dir)
+        mismatch = pin && !self.class.version_matches?(pin[:version], running)
+        fp_on_path = which('fp')
+
+        {
+          version: running,
+          ruby: RbConfig.ruby,
+          fp_version: Fp::VERSION,
+          gem_path: gem_path,
+          gem_bindir: Gem.bindir,
+          fp_on_path: fp_on_path,
+          fp_on_path_is_shim: fp_on_path&.include?('/shims/') || false,
+          pinned: pin && pin[:version],
+          pinned_by: pin && pin[:file],
+          mismatch: !!mismatch,
+          fixes: mismatch ? shim_fixes(pin, running) : []
+        }
+      end
+
+      def shim_fixes(pin, running)
+        version = pin[:version]
+        fixes = []
+        fixes << if pin[:manager] == 'mise' || which('mise')
+                   "mise exec ruby@#{version} -- gem install featureparity"
+                 elsif which('rbenv')
+                   'gem install featureparity && rbenv rehash   # run inside this directory'
+                 elsif which('asdf')
+                   'gem install featureparity && asdf reshim ruby   # run inside this directory'
+                 else
+                   "gem install featureparity   # run inside this directory, under Ruby #{version}"
+                 end
+        fixes << "export PATH=\"#{Gem.bindir}:$PATH\"   # or keep using fp from Ruby #{running}"
+        fixes
+      end
+
+      def gem_path
+        spec = Gem.loaded_specs['featureparity']
+        spec ? spec.full_gem_path : File.expand_path('../../..', __dir__)
+      end
+
+      def which(name)
+        ENV['PATH'].to_s.split(File::PATH_SEPARATOR).each do |entry|
+          candidate = File.join(entry, name)
+          return candidate if File.file?(candidate) && File.executable?(candidate)
+        end
+        nil
+      end
+
+      def config_report(dir)
+        r = config.resolved
+        project = ProjectConfig.discover(dir)
+        {
+          environment: r[:environment],
+          api_url: r[:api_url],
+          profile: r[:profile],
+          production: r[:environment] == 'production',
+          api_key_present: r[:api_key_present],
+          api_key_source: r[:api_key_source],
+          project_config: project.path,
+          project: project.project
+        }
+      end
+
+      # Which fp wrote this repo's AGENTS.md section, so a stale one is visible.
+      def agents_section_report(root)
+        Init::AGENT_DOC_CANDIDATES.filter_map do |name|
+          file = File.join(root, name)
+          next unless File.file?(file)
+
+          content = File.read(file)
+          next unless content.include?(Init::AGENTS_MARKER)
+
+          written = content[Init::AGENTS_VERSION_RE, 1]
+          { path: name, written_by: written, current: written == Fp::VERSION }
+        end
+      end
+
+      def print_report(report)
+        ruby = report[:ruby]
+        cfg = report[:config]
+        repo = report[:repo]
+
+        puts "fp #{ruby[:fp_version]} on Ruby #{ruby[:version]} (#{ruby[:ruby]})"
+        puts "  Gem:          #{ruby[:gem_path]}"
+        puts "  fp on PATH:   #{ruby[:fp_on_path] || '(not found)'}#{ruby[:fp_on_path_is_shim] ? '  [version-manager shim]' : ''}"
+        if ruby[:pinned]
+          state = ruby[:mismatch] ? '⚠ differs from the Ruby running fp' : 'matches'
+          puts "  Ruby pin:     #{ruby[:pinned]} (#{ruby[:pinned_by]}) — #{state}"
+        end
+        if ruby[:mismatch]
+          puts
+          puts "  This directory pins Ruby #{ruby[:pinned]}, but fp is installed under #{ruby[:version]}."
+          puts '  A version-manager shim runs `fp` with the pinned Ruby, where the gem is missing, and'
+          puts '  fails before fp starts (`mise ERROR No version is set for shim: fp`). Fix one of:'
+          ruby[:fixes].each { |fix| puts "    #{fix}" }
+        end
+
+        puts
+        puts 'Config'
+        env = cfg[:environment] || '(unknown)'
+        puts "  Environment:  #{env} (#{cfg[:api_url]})#{cfg[:profile] ? "  [profile #{cfg[:profile]}]" : ''}"
+        puts "  ⚠ Not production: writes go to '#{env}'. Run `fp whoami` to see why." unless cfg[:production]
+        puts "  API key:      #{cfg[:api_key_present] ? "present [from #{cfg[:api_key_source]}]" : 'not set (export FP_API_KEY=fp_... or fp setup)'}"
+        puts "  Project file: #{cfg[:project_config] ? "#{cfg[:project_config]} (project: #{cfg[:project] || '?'})" : 'none — run `fp init --detect`, then `fp init --project <slug>`'}"
+        report[:agents_section].each do |section|
+          stamp = section[:written_by] ? "fp #{section[:written_by]}" : 'an fp that predates version stamps'
+          note = section[:current] ? '' : ' — `fp init --force` refreshes it'
+          puts "  #{section[:path]}:    FeatureParity section written by #{stamp}#{note}"
+        end
+
+        puts
+        RepoDetector.print_summary(repo)
+      end
+    end
+  end
+end