featureparity 0.0.27 → 0.0.28

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4b09491a1b44b4ba693dfd567cdec5068d3410c577066435b541b2e9520ae04f
-  data.tar.gz: c9b7fb84bee3dbb3e8dfd8ee29f7c4d878747c0157efaa63fb020ead7934b2e7
+  metadata.gz: dd6b0a540d21e123a2ceb43cb9f23005c218319866ff7e079b951d6288199bb1
+  data.tar.gz: 6e0d61e3a3d9e6f590c6e978b134736877b5abc8da2a9a80332ff6cd203dbf58
 SHA512:
-  metadata.gz: cdf6cc31e230d20555285da1b44ee1816e94a88d3a5e3c02b22569cc63034d2f038d5183c12191f9ba446e5fdbc78a44ebe0b485e476f0dd5b9e021675338500
-  data.tar.gz: c9b9337383f9e7aecfa8caec130d99e3a1e93452481d14ffe1e0f95bd63c495480241d3b1578f0ff01ca5c7f81cc3b969a78cf232947a563cd307ade34b255c1
+  metadata.gz: fe1d8110555996bc72c885d502139e6f18dbef1d2ee8b8623eaf48c74dce6c40b33f46ffe4b42f09c9f92570380abab9b4dff77df3520d300ec6f43f35214890
+  data.tar.gz: 1f95d64e43e62a63411bd8cc665248777c3acdc58795e16552d4b5f671d3a1fb89a774bbf066e5f65f55bba7b716cc5f2fa78d51ea2b1a5afdc1fcd547acfa2d

data/lib/fp/cli.rb

@@ -7,6 +7,7 @@ module Fp
   class CLI
     COMMANDS = {
       'init' => Commands::Init,
+      'tutorial' => Commands::Tutorial,
       'projects' => Commands::Projects,
       'surfaces' => Commands::Surfaces,
       'showroom' => Commands::Showroom,
@@ -15,12 +16,14 @@ module Fp
       'propose' => Commands::Propose,
       'propose-change' => Commands::ProposeChange,
       'comment' => Commands::Comment,
+      'comments' => Commands::Comments,
       'history' => Commands::History,
       'analyze' => Commands::Analyze,
       'changes' => Commands::Changes,
       'report' => Commands::Report,
       'ci-report' => Commands::CiReport,
       'changed-tests' => Commands::ChangedTests,
+      'spot-check' => Commands::SpotCheck,
       'check' => Commands::Check,
       'matrix' => Commands::Matrix,
       'export' => Commands::Export,

data/lib/fp/client.rb

@@ -208,6 +208,12 @@ module Fp
       post("/api/requirements/#{requirement_id}/analyze", body)
     end
 
+    # POST /requirements/:id/test_review — Jev's read of whether these tests check what
+    # the requirement promises (`fp spot-check --jev`). Paid plans only (402 otherwise).
+    def review_spot_check_tests(requirement_id, tests)
+      post("/api/requirements/#{requirement_id}/test_review", { tests: tests })
+    end
+
     # GET /requirements/:id/changes
     #
     # A requirement's change history: what it was, what changed, who changed it, and
@@ -241,6 +247,22 @@ module Fp
       post("/api/requirements/#{requirement_id}/changes/#{change_id}/comment", params)
     end
 
+    # GET /requirements/:id/comments
+    #
+    # The team's comments on a requirement, oldest first, plus who can be tagged:
+    # `mentionable` (people) and `mentionable_agents` (Fizzy #1494).
+    def list_requirement_comments(requirement_id)
+      get("/api/requirements/#{requirement_id}/comments")
+    end
+
+    # POST /requirements/:id/comments
+    #
+    # Comment on a requirement. `mentions` are emails, `agent_mentions` agent key ids;
+    # tagged people are emailed and tagged agents fire the project's webhooks.
+    def comment_on_requirement(requirement_id, params)
+      post("/api/requirements/#{requirement_id}/comments", params)
+    end
+
     # DELETE /requirements/:id/changes/:change_id
     #
     # Withdraw an open proposal. Only the proposal's author can withdraw it; the
@@ -513,7 +535,7 @@ module Fp
       http.read_timeout = 30
 
       response = http.request(request)
-      parse_response(response)
+      parse_response(response, uri)
     rescue Net::OpenTimeout, Net::ReadTimeout => e
       { ok: false, error: "Request timed out: #{e.message}", status: 0 }
     rescue SocketError, Errno::ECONNREFUSED => e
@@ -522,13 +544,20 @@ module Fp
       { ok: false, error: "Request failed: #{e.message}", status: 0 }
     end
 
-    def parse_response(response)
+    def parse_response(response, uri = nil)
       body = response.body
       status = response.code.to_i
 
       # Try to parse as JSON
       data = JSON.parse(body) rescue nil
 
+      # A success that isn't JSON is almost always the web app answering in the API's
+      # place — FP_API_URL set to the site rather than its api host — and every command
+      # used to crash on it with "undefined method '[]' for nil" (Fizzy #1446).
+      if status >= 200 && status < 300 && data.nil? && !body.to_s.strip.empty?
+        return { ok: false, status: status, error: not_the_api_message(uri) }
+      end
+
       if status >= 200 && status < 300
         { ok: true, data: data, status: status }
       else
@@ -544,5 +573,27 @@ module Fp
         result
       end
     end
+
+    def not_the_api_message(uri)
+      origin = uri ? "#{uri.scheme}://#{uri.host}" : @base_url
+      message = +"#{origin} answered with a web page, not the FeatureParity API. " \
+                 'Point fp at the API host instead (check it with `fp whoami`).'
+      suggestion = api_host_for(uri&.host)
+      message << " Did you mean https://#{suggestion}? (export FP_API_URL=https://#{suggestion})" if suggestion
+      message
+    end
+
+    # The API host that sits beside a web-app host: featureparity.dev → api.featureparity.dev,
+    # an ephemeral <env>.dev.featureparity.dev → api-<env>.dev.featureparity.dev.
+    def api_host_for(host)
+      return nil if host.nil? || host.start_with?('api.', 'api-')
+      return nil unless host.end_with?('featureparity.dev')
+
+      labels = host.split('.')
+      return "api.#{host}" if labels.length <= 2
+      return "api.#{host}" if labels.first == 'dev' || labels.first == 'staging'
+
+      "api-#{host}"
+    end
   end
 end

data/lib/fp/commands/analyze.rb

@@ -153,6 +153,7 @@ module Fp
           'duplicate_of' => issues.find { |i| i['type'] == 'duplicate' }&.dig('duplicate_of'),
           'conflicts' => (analysis && analysis['conflicts']) || [],
           'suggestions' => (analysis && analysis['suggestions']) || [],
+          'warrants_requirement' => analysis && analysis['warrants_requirement'],
           'error' => error
         }
       end
@@ -199,6 +200,8 @@ module Fp
         end
         puts "    fails: #{entry['failed_checks'].join(', ')}" unless entry['failed_checks'].empty?
         puts "    issues: #{entry['issues'].map { |i| i['type'] }.join(', ')}" unless entry['issues'].empty?
+        warrants = warrants_line(entry['warrants_requirement'])
+        puts "    #{warrants}" if warrants && entry['warrants_requirement']['judgment'] == false
         puts "    error: #{entry['error']}" if entry['error']
       end
 
@@ -206,6 +209,8 @@ module Fp
         puts "#{entry['slug']} — #{entry['title']}"
         puts "  verdict: #{entry['verdict'] || '(none)'}   suggested: #{ACTIONS[entry['action']]}"
         puts "  superseded by: #{entry['duplicate_of']}" if entry['duplicate_of']
+        warrants = warrants_line(entry['warrants_requirement'])
+        puts "  #{warrants}" if warrants
         puts "  fails: #{entry['failed_checks'].join(', ')}" unless entry['failed_checks'].empty?
         entry['issues'].each { |i| puts "  issue: #{i['type']}" }
         entry['conflicts'].each do |c|
@@ -215,6 +220,18 @@ module Fp
         puts "  error: #{entry['error']}" if entry['error']
       end
 
+      # The analyzer's yes/no on whether the concept deserves to be a requirement at all.
+      # A "no" carries its reason so a human can decide to withdraw it — the CLI only
+      # reports it; nothing is withdrawn or proposed on the strength of the judgment.
+      def warrants_line(warrants)
+        return nil unless warrants.is_a?(Hash) && [true, false].include?(warrants['judgment'])
+
+        line = "warrants a requirement: #{warrants['judgment'] ? 'yes' : 'no'}"
+        line += " (confidence #{(warrants['confidence'].to_f * 100).round}%)" unless warrants['confidence'].nil?
+        line += " — #{warrants['reason']}" if !warrants['judgment'] && !warrants['reason'].to_s.empty?
+        line
+      end
+
       def progress(message)
         warn message unless output.json?
       end

data/lib/fp/commands/base.rb

@@ -202,6 +202,8 @@ module Fp
 
         unless project
           output.error("Project '#{project_slug_or_id}' not found")
+          hint = config&.environment_mismatch_hint
+          output.error(hint) if hint
           exit 1
         end
 

data/lib/fp/commands/comments.rb

@@ -0,0 +1,146 @@
+# frozen_string_literal: true
+
+module Fp
+  module Commands
+    # `fp comments <slug>` — the team's conversation on a requirement (Fizzy #1494).
+    #
+    # Without --body it prints the comments, oldest first. With --body it posts one, and
+    # --tag names who to tag: a teammate by email or name, or one of the team's agents by
+    # name or key name. Tagged people are emailed; each tagged agent fires the project's
+    # `requirement.agent_mentioned` webhooks, so whatever runs that agent can pick it up.
+    #
+    # Not to be confused with `fp comment`, which threads a comment onto a requirement's
+    # open change *proposal*.
+    class Comments < Base
+      KNOWN_FLAGS = { project: :string, body: :string, tag: :string }.freeze
+
+      help_summary "Read or post the team's comments on a requirement, tagging people or agents"
+      help_usage 'fp comments <slug> [--body "..." [--tag <who>,<who>]] --project <slug>'
+      help_flag :project, 'Project slug (falls back to .featureparity.yml)'
+      help_flag :body, 'Post this comment (omit to list the comments)'
+      help_flag :tag, 'Comma-separated people (email or name) or agents (name or key name) to tag'
+      help_example 'fp comments print_qr --project stowzilla'
+      help_example 'fp comments print_qr --body "The redesign dropped this screen — retire it?" --tag andy@example.com'
+
+      def run(args)
+        opts, positional = parse_flags(args, KNOWN_FLAGS)
+        require_project!(opts)
+
+        slug = positional.first
+        unless slug
+          output.error('Requirement slug is required. Usage: fp comments <slug> [--body "..."] [--project <project>]')
+          exit 1
+        end
+
+        project_id = resolve_project_id(opts[:project])
+        requirement = find_requirement!(project_id, slug)
+        listing = fetch!(client.list_requirement_comments(requirement['id']))
+
+        if opts[:body].nil?
+          print_comments(listing, slug)
+        else
+          post_comment(requirement, listing, opts, slug)
+        end
+      end
+
+      private
+
+      def post_comment(requirement, listing, opts, slug)
+        body = opts[:body].to_s
+        if body.strip.empty?
+          output.error('A comment needs some text. Pass --body "...".')
+          exit 1
+        end
+
+        people, agents = resolve_tags(opts[:tag], listing)
+        data = fetch!(client.comment_on_requirement(requirement['id'],
+                                                    body: body,
+                                                    mentions: people.map { |p| p['email'] },
+                                                    agent_mentions: agents.map { |a| a['id'] }))
+        comment = data['comment'] || {}
+
+        output.success(data) do
+          puts "Commented on '#{slug}'."
+          puts
+          print_comment(comment)
+          tagged_people = Array(comment['mentions']).map { |m| m['name'] }
+          tagged_agents = Array(comment['agent_mentions']).map { |m| m['name'] }
+          puts "#{tagged_people.join(', ')} will get an email." unless tagged_people.empty?
+          puts "#{tagged_agents.join(', ')} will be notified through the project's webhooks." unless tagged_agents.empty?
+        end
+      end
+
+      # Each --tag matches exactly one person (email or name) or agent (name or key
+      # name), case-insensitively. Unknown or ambiguous tags stop the command rather
+      # than post a comment that silently tags nobody.
+      def resolve_tags(raw, listing)
+        people = []
+        agents = []
+        raw.to_s.split(',').map(&:strip).reject(&:empty?).each do |tag|
+          wanted = tag.delete_prefix('@').downcase
+          person_hits = Array(listing['mentionable']).select do |p|
+            [p['email'], p['name']].compact.map(&:downcase).include?(wanted)
+          end
+          agent_hits = Array(listing['mentionable_agents']).select do |a|
+            [a['name'], a['key_name']].compact.map(&:downcase).include?(wanted)
+          end
+          hits = person_hits + agent_hits
+          if hits.empty?
+            output.error("Nobody on this project's team matches '#{tag}'. Run `fp comments <slug>` to see who can be tagged.")
+            exit 1
+          elsif hits.size > 1
+            output.error("'#{tag}' matches more than one person or agent; use an email or key name instead.")
+            exit 1
+          end
+          person_hits.empty? ? agents << agent_hits.first : people << person_hits.first
+        end
+        [people, agents]
+      end
+
+      def print_comments(listing, slug)
+        comments = Array(listing['comments'])
+        output.success(listing) do
+          puts "Comments on '#{slug}'"
+          puts
+          if comments.empty?
+            puts '  (no comments yet)'
+          else
+            comments.each { |comment| print_comment(comment) }
+          end
+          print_taggable(listing)
+        end
+      end
+
+      def print_comment(comment)
+        kind = comment['actor_kind'] == 'agent' ? ' (agent)' : ''
+        puts "* #{comment['actor_name'] || comment['actor']}#{kind} at #{comment['recorded_at']}"
+        comment['body'].to_s.each_line { |line| puts "  > #{line.chomp}" }
+        tags = Array(comment['mentions']) + Array(comment['agent_mentions'])
+        puts "  tagged: #{tags.map { |t| t['name'] }.join(', ')}" unless tags.empty?
+        puts
+      end
+
+      def print_taggable(listing)
+        people = Array(listing['mentionable']).map { |p| "#{p['name']} <#{p['email']}>" }
+        agents = Array(listing['mentionable_agents']).map { |a| "#{a['name']} (#{a['key_name']}, #{a['owner_name']}'s agent)" }
+        return if people.empty? && agents.empty?
+
+        puts 'Can be tagged with --tag:'
+        people.each { |p| puts "  #{p}" }
+        agents.each { |a| puts "  #{a}" }
+      end
+
+      def find_requirement!(project_id, slug)
+        fetch!(client.find_requirement_by_slug(project_id, slug))['requirement']
+      end
+
+      def fetch!(result)
+        unless result[:ok]
+          output.error(result[:error], status: result[:status])
+          exit 1
+        end
+        result[:data]
+      end
+    end
+  end
+end

data/lib/fp/commands/help.rb

@@ -39,6 +39,7 @@ module Fp
 
           COMMANDS
             init --project <slug>             Onboard this repo: config, CI gate, agent docs
+            tutorial                          Write Hexhaven, a sample repo to practise on
             projects                          List projects you have access to
             projects show <slug>              View a project and its surfaces
             projects create <slug> --name ... Create a project (owned by your key's owner)
@@ -62,6 +63,8 @@ module Fp
             propose-change <slug> --no-parent Propose un-nesting a child to top level
             propose-change <slug> --withdraw  Withdraw your own open proposal (to amend it)
             comment <slug> --body "..."       Comment on a requirement's open change proposal
+            comments <slug>                   Read the team's comments on a requirement
+            comments <slug> --body "..." [--tag who,...]  Comment on a requirement, tagging people or agents
             history <slug> --project <slug>   Show a requirement's change history + diffs
             analyze [<slug>] --project <slug> Triage requirement quality (read-only; never proposes)
             changes [--source-url URL] [--github-pr]  Show or publish work-item-linked activity
@@ -76,6 +79,7 @@ module Fp
             ci-report --junit <file> --pr URL Ingest a PR's CI results as pr_passing — CI only
             changed-tests                     List unresolved bound-test revision findings
             changed-tests assess <id> ...     Explain whether an exact revision still proves its requirement
+            spot-check [<slug>...]            Check requirements' tests prove them (random, --count, --all, --test)
             check                             Enforce parity; exits non-zero on violations
             matrix --project <slug>           Show the parity matrix
             export --project <slug>           Export all requirements as a Markdown document
@@ -159,6 +163,30 @@ module Fp
             A stale or later candidate needs a new assessment. A PR candidate becomes accepted only
             when a default-branch CI report later observes the same fingerprint.
 
+          SPOT CHECKS
+            A green receipt says a marked test ran and passed, not that it checks what the
+            requirement promises. `fp spot-check` picks an active requirement with evidence at
+            random, prints its acceptance beside the source of every locally marked test, and
+            gives the agent running it a brief: match each clause to an assertion, then break
+            the product code and confirm a test fails. Run it on a schedule or by hand.
+
+              fp spot-check                     # a random pick; prints the seed to repeat it
+              fp spot-check --count 5 --surface cli --json
+              fp spot-check print_container_qr print_label   # chosen requirements
+              fp spot-check --all               # every active requirement with evidence
+              fp spot-check --test test/qr_test.rb:42        # the test there, and its requirement
+              fp spot-check --count 3 --prompt | claude -p   # hand it straight to an agent
+              fp spot-check --jev               # add Jev's first read (paid plans)
+
+            `--prompt` prints the spot check as instructions for an agent, with what to report
+            back. `--jev` asks Jev, before the agent starts, whether each requirement's tests
+            appear to cover its acceptance, and which gap is likeliest. It's a hint for aiming
+            the probe, not a verdict. Jev is for paid plans: without one the spot check runs
+            without it.
+
+            It records nothing and never edits a test or a requirement. A test that stays
+            green when the promise is broken goes to a human.
+
           AUTHENTICATION
             Set FP_API_KEY environment variable, or use a profile:
 

data/lib/fp/commands/history.rb

@@ -31,7 +31,9 @@ module Fp
         'removal_proposed' => 'deletion proposed',
         'change_approved' => 'change approved',
         'change_rejected' => 'change rejected',
-        'decision_recorded' => 'decision recorded'
+        'decision_recorded' => 'decision recorded',
+        'change_commented' => 'commented on the proposal',
+        'commented' => 'commented'
       }.freeze
 
       # A member's own stance on a requirement that already has a status (Fizzy #1478),
@@ -110,6 +112,7 @@ module Fp
         puts "* #{label} — #{actor} (#{kind}) at #{format_time(change['recorded_at'])}"
         puts "  #{change['reason']}" if present?(change['reason'])
         puts "  note: #{change['note']}" if change['type'] == 'decision_recorded' && present?(change['note'])
+        print_comment(change) if %w[commented change_commented].include?(change['type'])
         print_source(change['source'])
         print_diff(change['changes'])
         print_evidence_diff(change['evidence_diff'])
@@ -117,6 +120,14 @@ module Fp
         puts
       end
 
+      # The team's comments (Fizzy #1494) and comments on a proposal, so an agent reading
+      # the history sees the discussion, not just that one happened.
+      def print_comment(change)
+        change['body'].to_s.each_line { |line| puts "  > #{line.chomp}" } if present?(change['body'])
+        mentions = Array(change['mentions'])
+        puts "  tagged: #{mentions.join(', ')}" unless mentions.empty?
+      end
+
       def print_source(source)
         return if source.nil? || source.empty?
 

data/lib/fp/commands/init.rb

@@ -88,6 +88,15 @@ module Fp
         report(project_slug, root, written, skipped, opts)
       end
 
+      # The same agent brief `fp init` writes, for another command to put in a repo it
+      # creates (`fp tutorial`'s Hexhaven), so the two can never drift apart. Appends to
+      # an existing AGENTS.md/CLAUDE.md the way init does. Returns the paths written.
+      def self.write_agent_docs!(root, project_slug)
+        written = []
+        new.send(:write_agent_docs, root, project_slug, { dir: root }, written, [])
+        written.map(&:first)
+      end
+
       private
 
       def write_project_config(root, project_slug, level, opts, written, skipped)

data/lib/fp/commands/projects.rb

@@ -87,7 +87,11 @@ module Fp
         output.success(result[:data]) do
           if projects.empty?
             puts 'No projects found.'
-            puts 'Create one with: fp projects create <slug> --name "<Name>"'
+            if (hint = config&.environment_mismatch_hint)
+              puts hint
+            else
+              puts 'Create one with: fp projects create <slug> --name "<Name>"'
+            end
           else
             headers = %w[SLUG NAME SURFACES]
             rows = projects.map do |w|

data/lib/fp/commands/propose.rb

@@ -108,8 +108,10 @@ module Fp
         end
 
         requirement = result[:data]['requirement']
+        feedback = draft_feedback(requirement)
+        data = result[:data].merge('analysis' => feedback[:analysis], 'analysis_error' => feedback[:error]).compact
 
-        output.success(result[:data]) do
+        output.success(data) do
           puts "Created requirement '#{requirement['slug']}' as DRAFT."
           puts
           puts "  Title:    #{requirement['title']}"
@@ -125,11 +127,42 @@ module Fp
           puts '⚠️  This requirement is a DRAFT.'
           puts '   A human must activate it in the web app before it appears in the parity matrix.'
           puts '   Agents cannot activate requirements.'
+          print_feedback(feedback, requirement['slug'])
         end
       end
 
       private
 
+      # Quality feedback on the draft just created, as part of the same command, so an
+      # agent learns at once that its draft is weak or shouldn't exist and can fix or
+      # withdraw it before a human looks (requirement_analysis_runs_on_draft). It never
+      # undoes the draft: when analysis is unavailable the draft stands and we say so.
+      def draft_feedback(requirement)
+        result = client.analyze_requirement(requirement['id'])
+        return { analysis: result[:data]['analysis'] } if result[:ok] && result[:data].is_a?(Hash) && result[:data]['analysis']
+
+        { error: result[:error] || 'no analysis came back' }
+      end
+
+      def print_feedback(feedback, slug)
+        puts
+        if feedback[:error]
+          puts "Quality feedback could not be produced: #{feedback[:error]}"
+          puts "The draft was still created. Try again later with `fp analyze #{slug}`."
+          return
+        end
+
+        analysis = feedback[:analysis]
+        puts "Quality feedback: #{analysis['verdict'] || 'no verdict'}"
+        Array(analysis['issues']).each do |issue|
+          puts "  - #{issue['type'].to_s.tr('_', ' ')}"
+        end
+        Array(analysis['suggestions']).first(3).each { |suggestion| puts "  → #{suggestion}" }
+        return unless %w[questionable needs_work].include?(analysis['verdict'])
+
+        puts "Revise it with `fp propose-change #{slug} ...`, or withdraw it if it shouldn't be a requirement."
+      end
+
       # Parse a comma-separated --required-types list into a normalized array. Returns []
       # when the flag is absent (meaning "any test counts / inherit project default").
       #

data/lib/fp/commands/propose_change.rb

@@ -23,16 +23,16 @@ module Fp
       help_flag :parent, "Set the parent requirement's slug"
       help_flag :no_parent, 'Propose un-nesting the requirement back to the top level (clears --parent)'
       help_flag :slug, 'Proposed new slug (evidence follows; markers still need updating)'
-      help_flag :reason, 'What prompted this change (use this, not --source-*, to record the prompt)'
+      help_flag :reason, 'What prompted this change, in words (recorded on the change)'
       help_flag :removal, 'Propose deleting the requirement instead of changing it'
       help_flag :withdraw, 'Take back the open proposal you authored, restoring the requirement as it was'
-      help_flag :source_type, "Correct the requirement's recorded origin type (not the change's prompt)"
-      help_flag :source_url, "Correct the requirement's recorded origin URL"
-      help_flag :source_context, "Correct the requirement's recorded origin context"
+      help_flag :source_type, "Where this proposal came from (recorded on the change; the requirement's origin is kept)"
+      help_flag :source_url, 'URL of the card/issue/thread that prompted this proposal'
+      help_flag :source_context, 'Free-form note about what prompted this proposal'
       help_example 'fp propose-change print_qr --project stowzilla --acceptance "QR scans after 24h at -20C" --reason "Cold-chain rollout"'
       help_example 'fp propose-change print_qr --removal --reason "Superseded by print_container_label"'
-      help_note "Applies the change and drops the requirement to draft for a human to review. Use --reason\n" \
-                "to say what prompted it; --source-* overwrite the requirement's own origin fields."
+      help_note "Applies the change and drops the requirement to draft for a human to review. --reason and\n" \
+                "--source-* record what prompted the proposal in its history; the requirement's own origin is unchanged."
 
       KNOWN_FLAGS = {
         project: :string, name: :string, why: :string, acceptance: :string,

data/lib/fp/commands/report.rb

@@ -208,7 +208,10 @@ module Fp
 
       # Batch-upload evidence from a JUnit XML report.
       def run_junit(opts)
-        require_project!(opts)
+        # The report's own checkout says which project it is: discovering from the
+        # report's directory (and up) means `fp report --junit hexhaven/junit.xml` run
+        # from a parent folder reads hexhaven's .featureparity.yml, not the parent's.
+        require_project!(opts, ProjectConfig.discover(File.dirname(File.expand_path(opts[:junit].to_s))))
         require_flag(opts, :repo)
         # --surface is the default for markers that don't pin their own surface
         # (e.g. `fp:slug@api,web`). It's only strictly required when at least one
@@ -244,6 +247,19 @@ module Fp
         result = Fp::JUnit.bind_markers(testcases, base_dir: base_dir,
                                         default_surface: opts[:surface],
                                         default_test_type: opts[:test_type])
+        # Run from outside the checkout, paths in the report resolve from nowhere. When
+        # nothing binds from here and no --base-dir was given, try the report's own
+        # directory before giving up.
+        report_dir = File.dirname(File.expand_path(opts[:junit].to_s))
+        if result[:bindings].empty? && opts[:base_dir].nil? && report_dir != File.expand_path(base_dir)
+          retried = Fp::JUnit.bind_markers(testcases, base_dir: report_dir,
+                                           default_surface: opts[:surface],
+                                           default_test_type: opts[:test_type])
+          if retried[:bindings].any?
+            base_dir = report_dir
+            result = retried
+          end
+        end
         bindings = result[:bindings]
         unmatched = result[:unmatched]
         missing_surface = result[:missing_surface] || []

data/lib/fp/commands/show.rb

@@ -59,7 +59,13 @@ module Fp
         result = client.list_evidence(project_id, slug: slug)
         return [] unless result[:ok]
 
-        result[:data]['evidence'] || []
+        # The server names the receipts CI has since spoken for; flag them on the rows so
+        # both the listing and --json say so, rather than a stale `present` reading as a
+        # second verdict beside CI's (Fizzy #1762).
+        superseded = Array(result[:data]['superseded_ids'])
+        (result[:data]['evidence'] || []).map do |e|
+          superseded.include?(e['id']) ? e.merge('superseded' => true) : e
+        end
       end
 
       def fetch_attachments(requirement_id)
@@ -156,8 +162,13 @@ module Fp
             .group_by { |e| e['surface'] }
             .each do |surface, records|
               puts "  #{surface}:"
-              records.each do |e|
-                puts "    Status:  #{e['status']}"
+              # The receipts the matrix counts first; superseded ones after.
+              records.partition { |e| !e['superseded'] }.flatten(1).each do |e|
+                if e['superseded']
+                  puts "    Status:  superseded by CI (was #{e['status']}; CI's latest run is what counts)"
+                else
+                  puts "    Status:  #{e['status']}"
+                end
                 # A pull request's CI may have written over the merged verdict; show both
                 # when they differ so "failing" next to "PR: …" reads as the branch's
                 # result, not the default branch's.