featureparity 0.0.24 → 0.0.26

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4e68b70dce16d28e928ead4413623002ccda97f4508f62bbe6d980c8bb29a21c
-  data.tar.gz: e630a9bd6f49db70c343f6374cd3c049a9c9fb4b786251dd313b76a177e0a1f9
+  metadata.gz: 2403a7e55f95df5cf1821375442902c0a06784c26186f1e2fc1ae2e474ee937b
+  data.tar.gz: 4cbb3354c710f6d6e19114b2e2c28e533251c10bfa4a93c0a917ff73e5ebce93
 SHA512:
-  metadata.gz: 55bde2507b4cfccbe49b8d799d0b3e7efba22c0298450e823a3ac86299ec4d392b0e51f13c3c643a2abc1d60f1d68d091074420c0928fbbcf9da6947fea296d1
-  data.tar.gz: c5d9754313a59721bfc78f5d4e65d4924ef1f5120659037cace19e6ee816a96dea0e467f47ad285cf03003ba37ed836501754c5592f9b22385f5a52315be5cae
+  metadata.gz: 8a065b839f21e0bdf4194f65b93c233abf3e09ef11a50f96d0259d68609fc1c6e89e3d07e760a5a8d3b3bb12b849b7fdb7ea1c3a5fa65fc59b4befa053595366
+  data.tar.gz: 50e977bdf9a66c6f24a8a264d9334a506d5f15379f8e9aeaa8635d6cf84b5f9eee526e990c6e9b1a041631f1e15b7115e3ed3484311130f1fd23ca0ad7d35cde

data/lib/fp/client.rb

@@ -281,7 +281,7 @@ module Fp
     # only do that by fetching the test files from GitHub, which fails silently on a
     # private repo, so resolved results are always sent when we have them.
     def ingest_ci_results(project_id, ci_url:, surface:, junit_xml:, pr_url: nil, results: nil,
-                          test_revisions: nil, unmarked_failures: nil)
+                          test_revisions: nil, unmarked_failures: nil, orphan_markers: nil, sha: nil)
       body = {
         ci_url: ci_url,
         surface: surface,
@@ -289,6 +289,9 @@ module Fp
       }
       # Only send pr_url when set, so a merged-branch run stays a plain ingest.
       body[:pr_url] = pr_url if pr_url && !pr_url.empty?
+      # The checkout commit, so the receipt (or a PR run's branch verdict) links the
+      # exact revision the suite ran at.
+      body[:sha] = sha if sha && !sha.empty?
       body[:results] = results if results && !results.empty?
       # Testcase-level source receipts stay separate from aggregate Evidence outcomes:
       # several tests may back one cell, and each can change independently.
@@ -296,6 +299,10 @@ module Fp
       # Loose ends: failing tests with no fp:<slug> marker. The server stores them so the
       # matrix can surface a red suite whose failures aren't bound to any requirement.
       body[:unmarked_failures] = unmarked_failures if unmarked_failures && !unmarked_failures.empty?
+      # Orphan markers: fp:<slug> markers that bind to no requirement. Sent whenever the
+      # run could tell (an empty array included), so the server replaces the default
+      # branch's recorded set and a fixed marker drops off; nil means "couldn't tell".
+      body[:orphan_markers] = orphan_markers unless orphan_markers.nil?
 
       post("/api/projects/#{project_id}/ci_results", body)
     end
@@ -349,13 +356,21 @@ module Fp
     # `results` are the run's outcomes already bound to their markers locally (see
     # ingest_ci_results). Sending them is what lets a surface whose repo isn't registered
     # — or a private one the server can't read — be previewed at all.
-    def preview_parity(project_id, surface:, junit_xmls:, level: nil, results: nil)
+    def preview_parity(project_id, surface:, junit_xmls:, level: nil, results: nil,
+                       pull_request: false, pr_url: nil)
       # Older API deployments read `surface_filter` for report scoping while `surface`
       # identifies the run's overlay. Send both during the rollout; current servers use
       # `surface` for both meanings.
       body = { surface: surface, surface_filter: surface, junit_xmls: Array(junit_xmls) }
       body[:results] = results if results && !results.empty?
       body[:level] = level if level
+      # A pull request's run is judged on what it changes, not on what the default branch
+      # already owes. Only sent when asked for, so a default-branch run stays the
+      # standing verdict.
+      if pull_request
+        body[:pull_request] = true
+        body[:pr_url] = pr_url if pr_url && !pr_url.to_s.empty?
+      end
       post("/api/projects/#{project_id}/parity/preview", body)
     end
 

data/lib/fp/commands/check.rb

@@ -35,18 +35,30 @@ module Fp
     # that isn't clean yet — you get the annotations without blocking every merge on day
     # one. Prefer setting the project's level to `regression` over living on --warn-only
     # forever, since a warn-only gate is one nobody reads.
+    #
+    # `--pr [url]` (with --junit) asks the pull-request question instead of the standing
+    # one: "does this change make parity worse?" The server judges the run against the
+    # merged baseline and fails only on what the run introduced — a bound test gone red, a
+    # bound test that vanished, a non-green test added where there was none. Whatever
+    # master already owed is listed as inherited and not counted, so a PR that did
+    # everything right isn't red because a removal proposal is still waiting on a human.
+    # The default-branch gate (no --pr) keeps asking the standing question and stays red
+    # until someone decides — that is where that signal belongs (Fizzy #1506).
     class Check < Base
       help_summary 'Enforce parity; exits non-zero when the project violates its level'
-      help_usage 'fp check [--project <slug>] [--surface X] [--level L] [--junit FILE]... [--warn-only]'
+      help_usage 'fp check [--project <slug>] [--surface X] [--level L] [--junit FILE]... [--pr [URL]] [--warn-only]'
       help_flag :project, 'Project slug (falls back to .featureparity.yml)'
       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 :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_example 'fp check', 'Gate on recorded state (project from .featureparity.yml)'
-      help_example 'fp check --surface api --junit junit.xml', "Gate a PR branch on its own results"
+      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_note "Exit 0 = passed, 1 = violations (or request failed). The level lives on the project\n" \
                 'server-side; --level only overrides this one run.'
@@ -58,9 +70,17 @@ module Fp
         level: :string,
         junit: :string,
         base_dir: :string,
+        # `--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
       }.freeze
 
+      # How many inherited violations to list before summarising the rest. They are
+      # informational — the gate already said they don't count — and on a project with a
+      # long standing backlog a full table buries the regressions that do.
+      INHERITED_PREVIEW_ROWS = 10
+
       def run(args)
         # Collect every --junit occurrence (parse_flags keeps only the last of a repeated
         # flag), matching `fp ci-report`.
@@ -73,6 +93,13 @@ module Fp
         surface = opts[:surface] || project_config.surface
         level = opts[:level] || project_config.enforcement
 
+        # The pull-request question needs a run to compare: without --junit there is
+        # nothing to judge against the baseline.
+        if opts[:pr] && junit_paths.empty?
+          output.error('--pr needs --junit: a pull request is judged on its own run\'s results.')
+          exit 1
+        end
+
         project_id = resolve_project_id(project_slug)
 
         result =
@@ -91,6 +118,13 @@ module Fp
         violations = report['violations'] || []
         passed = report['passing']
 
+        # An API that predates --pr ignores the flag and answers the standing question.
+        # Say so rather than let a reader believe the verdict was scoped to the change.
+        if opts[:pr] && !report['pull_request']
+          warn 'Warning: the API did not apply --pr (it predates pull-request mode); ' \
+               'this verdict counts every violation, including those the default branch already has.'
+        end
+
         render(report, violations, passed, project_slug, opts)
 
         # A failing gate is the whole point of the command, so it must be the exit code
@@ -130,7 +164,10 @@ module Fp
           surface: surface,
           junit_xmls: junit_paths.map { |p| File.read(p) },
           level: level,
-          results: resolve_results(junit_paths, surface, opts)
+          results: resolve_results(junit_paths, surface, opts),
+          pull_request: !!opts[:pr],
+          # `--pr` alone parses as true; `--pr <url>` as the URL.
+          pr_url: (opts[:pr].is_a?(String) ? opts[:pr] : nil)
         )
       end
 
@@ -179,7 +216,13 @@ module Fp
           scope = report['surface'] ? " (surface: #{report['surface']})" : ''
           puts "FeatureParity gate: #{project_slug}#{scope}"
           puts "Enforcement level: #{report['level']}"
-          if report['preview']
+          if report['pull_request']
+            reported = Array(report['preview_surfaces']).join(', ')
+            puts "Mode: pull request — judging this run's results#{reported.empty? ? '' : " for #{reported}"} " \
+                 'against what the default branch has recorded (nothing saved)'
+            puts '      Only parity this change makes worse fails the gate; what the default branch ' \
+                 'already owes is listed, not counted.'
+          elsif report['preview']
             reported = Array(report['preview_surfaces']).join(', ')
             puts "Mode: preview — evaluating this run's results#{reported.empty? ? '' : " for #{reported}"} (nothing saved)"
           end
@@ -198,10 +241,14 @@ module Fp
 
           print_state_counts(summary)
           print_scope_notice(report)
-          print_violations(violations)
+          print_violations(violations, report)
+          print_improvements(report)
+          print_unmeasured(report)
+          print_inherited(report)
           print_orphans(report)
           print_pending_reviews(report, project_slug)
           print_unscoped_warning(summary, project_slug)
+          print_next_steps(report, violations)
           print_verdict(passed, violations, opts, report)
         end
       end
@@ -252,10 +299,98 @@ module Fp
         puts
       end
 
-      def print_violations(violations)
+      def print_violations(violations, report = {})
         return if violations.empty?
 
-        puts "#{violations.size} violation(s):"
+        if report['pull_request']
+          puts "#{violations.size} regression(s) introduced by this change:"
+        else
+          puts "#{violations.size} violation(s):"
+        end
+        violations_table(violations)
+        puts
+      end
+
+      # Pull-request mode: what the default branch already owed. Listed so a reviewer can
+      # see why the standing gate is red and that this change didn't cause it; never
+      # counted, so never the reason this check fails. Capped — the regressions above are
+      # what the reader needs to act on, and a long backlog shouldn't bury them.
+      def print_inherited(report)
+        return unless report['pull_request']
+
+        inherited = report['inherited_violations'] || []
+        return if inherited.empty?
+
+        puts "#{inherited.size} violation(s) already on the default branch (not counted against this change):"
+        violations_table(inherited.first(INHERITED_PREVIEW_ROWS))
+        if inherited.size > INHERITED_PREVIEW_ROWS
+          puts "  … and #{inherited.size - INHERITED_PREVIEW_ROWS} more. " \
+               'Run fp check without --junit to see the standing verdict in full.'
+        end
+        puts
+      end
+
+      # Pull-request mode: the cells this run fixed. The positive half of the verdict —
+      # an agent checking its own branch needs to see that the requirement it set out to
+      # cover went green, not only that nothing broke.
+      def print_improvements(report)
+        return unless report['pull_request']
+
+        fixed = report['improvements'] || []
+        return if fixed.empty?
+
+        puts "#{fixed.size} cell(s) this change fixed:"
+        output.table(
+          %w[SLUG SURFACE WAS NOW],
+          fixed.map do |f|
+            [f['slug'], [f['surface'], presence(f['test_type'])].compact.join(' / '),
+             "#{Parity.glyph(f['from'])} #{f['from']}", "#{Parity.glyph(f['to'])} #{f['to']}"]
+          end
+        )
+        puts
+      end
+
+      # Results bound to requirements the gate doesn't measure yet — drafts awaiting a
+      # human's activation. Without this, an agent that proposed a requirement and wrote
+      # its test would hear nothing about the one thing its branch was for.
+      def print_unmeasured(report)
+        unmeasured = report['unmeasured'] || []
+        return if unmeasured.empty?
+
+        puts "#{unmeasured.size} result(s) bound to draft requirement(s) — not measured until a human activates them:"
+        output.table(
+          %w[SLUG SURFACE RESULT],
+          unmeasured.map { |u| [u['slug'], u['surface'], "#{Parity.glyph(u['status'])} #{u['status']}"] }
+        )
+        puts
+      end
+
+      # What to do next, grouped by who does it. The server names an action and an owner
+      # on every violation; this just reads them out so an agent asked to bring the
+      # project up to parity can take the `agent` rows and leave the `human` ones alone.
+      # On a pull request only the introduced violations are listed here — the inherited
+      # backlog is master's job, not this branch's.
+      def print_next_steps(report, violations)
+        rows = violations.select { |v| v['action'] }
+        rows += (report['orphans'] || []).reject { |o| o['inherited'] }.select { |o| o['action'] } if report['orphans_violate']
+        return if rows.empty?
+
+        puts 'Next steps:'
+        %w[agent human].each do |owner|
+          mine = rows.select { |v| v['owner'] == owner }
+          next if mine.empty?
+
+          puts "  #{owner == 'agent' ? 'An agent can fix' : 'Waiting on a human'} (#{mine.size}):"
+          mine.group_by { |v| v['action'] }.each do |action, group|
+            slugs = group.map { |v| [v['slug'], v['surface']].compact.join('@') }.uniq
+            puts "    #{action}: #{slugs.first(8).join(', ')}#{slugs.size > 8 ? ", … #{slugs.size - 8} more" : ''}"
+            puts "      → #{group.first['action_hint']}" if group.first['action_hint']
+          end
+        end
+        puts
+      end
+
+      def violations_table(violations)
         # Show the TYPE column only when some requirement demands specific test types —
         # otherwise it's an empty column of dashes on every project that doesn't use the
         # feature.
@@ -275,7 +410,6 @@ module Fp
             end
           )
         end
-        puts
       end
 
       # nil/blank → nil, so `presence(x)` reads as falsey in a guard.
@@ -293,20 +427,35 @@ module Fp
       # as a violation when it counts and a note when it doesn't. Only the --junit path
       # has a run to find these in; plain `fp check` reads recorded state and shows none.
       def print_orphans(report)
-        orphans = report['orphans'] || []
-        return if orphans.empty?
+        all = report['orphans'] || []
+        return if all.empty?
+
+        # On a pull request the default branch's own dangling markers are listed apart
+        # and never counted — this branch didn't add them.
+        inherited, orphans = all.partition { |o| o['inherited'] }
+
+        unless orphans.empty?
+          violates = report['orphans_violate']
+          lead = violates ? "#{orphans.size} orphan marker(s) — a violation at this level:" \
+                          : "#{orphans.size} orphan marker(s) (not failing the gate at this level):"
+          puts lead
+          output.table(
+            %w[SLUG SURFACE WHERE],
+            orphans.map { |o| [o['slug'], o['surface'], marker_location(o)] }
+          )
+          puts 'These tests are marked fp:<slug> for a requirement that does not exist. ' \
+               'Either propose it (fp propose --slug <slug> ...) or fix the marker\'s slug — ' \
+               'FP will not invent a requirement from a marker.'
+          puts
+        end
 
-        violates = report['orphans_violate']
-        lead = violates ? "#{orphans.size} orphan marker(s) — a violation at this level:" \
-                        : "#{orphans.size} orphan marker(s) (not failing the gate at this level):"
-        puts lead
+        return if inherited.empty?
+
+        puts "#{inherited.size} orphan marker(s) already on the default branch (not counted against this change):"
         output.table(
           %w[SLUG SURFACE WHERE],
-          orphans.map { |o| [o['slug'], o['surface'], marker_location(o)] }
+          inherited.map { |o| [o['slug'], o['surface'], marker_location(o)] }
         )
-        puts 'These tests are marked fp:<slug> for a requirement that does not exist. ' \
-             'Either propose it (fp propose --slug <slug> ...) or fix the marker\'s slug — ' \
-             'FP will not invent a requirement from a marker.'
         puts
       end
 
@@ -341,6 +490,29 @@ module Fp
         # reads "Gate passed" as "the whole project is covered" (Fizzy #1490).
         scope = report['scoped'] ? " for surface '#{report['surface']}' (other required surfaces not checked)" : ''
 
+        # A pull request's verdict is about the change, and the verdict line says so —
+        # "Gate passed" next to a red default branch would otherwise read as a
+        # contradiction. The baseline count tells the reviewer what master still owes.
+        if report['pull_request']
+          inherited = (report['inherited_violations'] || []).size
+          standing = inherited.positive? ? " #{inherited} violation(s) already on the default branch are not counted here." : ''
+          # Orphan markers the run added count too when the level says so; name them so a
+          # fail with no red cell doesn't read as "introduces 0 regressions".
+          added_orphans = report['orphans_violate'] ? (report['orphans'] || []).count { |o| !o['inherited'] } : 0
+          introduced = []
+          introduced << "#{violations.size} parity regression(s)" if violations.any? || added_orphans.zero?
+          introduced << "#{added_orphans} orphan marker(s)" if added_orphans.positive?
+          if passed
+            puts "Gate passed#{scope}: this change introduces no parity regressions.#{standing}"
+          elsif opts[:warn_only]
+            puts "Gate FAILED: this change introduces #{introduced.join(' and ')} — " \
+                 'exiting 0 because --warn-only was given.'
+          else
+            puts "Gate FAILED: this change introduces #{introduced.join(' and ')}.#{standing}"
+          end
+          return
+        end
+
         if passed
           puts "Gate passed#{scope}."
         elsif opts[:warn_only]

data/lib/fp/commands/ci_report.rb

@@ -107,17 +107,23 @@ module Fp
         repo = opts[:repo] || presence(ENV['GITHUB_REPOSITORY'])
 
         totals = { created: 0, updated: 0, missing_failing: 0, reports: [], resolved: 0,
-                   unmatched: 0, unknown: [], unmarked_failures: [], test_revisions: 0,
+                   unmatched: 0, unknown: [], orphan_markers: [], unmarked_failures: [], test_revisions: 0,
                    findings_opened: 0, baselines_accepted: 0 }
 
         resolved_reports = junit_paths.map do |path|
           resolved = resolve_results(path, opts, commit_sha: commit_sha, repo: repo)
           totals[:unmatched] += resolved[:unmatched]
 
-          results, unknown = partition_known(resolved[:results], known)
-          test_revisions, revision_unknown = partition_known(resolved[:test_revisions], known)
+          results, orphans = partition_known(resolved[:results], known)
+          test_revisions, revision_orphans = partition_known(resolved[:test_revisions], known)
           totals[:resolved] += results.length
-          totals[:unknown].concat(unknown).concat(revision_unknown)
+          totals[:unknown].concat(orphans.map { |r| r[:slug] }).concat(revision_orphans.map { |r| r[:slug] })
+          # The orphan markers themselves, with where they were found, for the server to
+          # record as the default branch's set (see Client#ingest_ci_results).
+          totals[:orphan_markers].concat(orphans.map do |r|
+            { slug: r[:slug], surface: r[:surface], name: r[:title],
+              source_file: r[:source_file], source_line: r[:source_line] }
+          end)
           totals[:unmarked_failures].concat(resolved[:unmarked_failures])
           totals[:test_revisions] += test_revisions.length
 
@@ -140,9 +146,13 @@ module Fp
           # with servers old enough to ignore client-resolved results.
           junit_xml: resolved_reports.first[:xml],
           pr_url: opts[:pr],
+          sha: commit_sha,
           results: combined_results,
           test_revisions: combined_revisions,
-          unmarked_failures: totals[:unmarked_failures]
+          unmarked_failures: totals[:unmarked_failures],
+          # nil when the requirement list couldn't be fetched (known.nil?) — then nothing
+          # was partitioned and we must not tell the server "no orphans this run".
+          orphan_markers: known.nil? ? nil : totals[:orphan_markers].uniq
         )
 
         unless result[:ok]
@@ -261,11 +271,12 @@ module Fp
         end.values
       end
 
+      # Split results into those whose slug names a requirement and the orphans. Returns
+      # the orphan *entries* (not just slugs) so the run can report where each was found.
       def partition_known(results, known)
         return [results, []] if known.nil?
 
-        kept, unknown = results.partition { |r| known.include?(r[:slug]) }
-        [kept, unknown.map { |r| r[:slug] }.uniq]
+        results.partition { |r| known.include?(r[:slug]) }
       end
 
       # Reports can be split into shards. Keep every independently identified testcase,

data/lib/fp/commands/init.rb

@@ -305,6 +305,13 @@ module Fp
                 # had its fp: marker stripped: the remaining tests still pass, so a plain
                 # suite stays green while the requirement loses its only proof. Use one
                 # call per surface.
+                #
+                # On a pull request add --pr so the verdict is about the change: only
+                # parity the branch makes worse fails it, and what the default branch
+                # already owes is listed, not counted. A push to the default branch gets
+                # no --pr and the standing verdict:
+                #
+                #   fp check --surface <surface-key> --junit junit.xml --pr "${{ github.event.pull_request.html_url }}"
                 - name: Check parity
                   if: env.HAVE_FP_KEY == 'true'
                   env:

data/lib/fp/commands/report.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require 'open3'
+require 'set'
 require_relative 'attach'
 
 module Fp
@@ -37,11 +39,14 @@ module Fp
       help_flag :junit, 'JUnit XML report to batch-upload evidence from'
       help_flag :base_dir, 'Where relative test-file paths in the report resolve from'
       help_flag :attach_media, 'With --junit: upload the videos/screenshots the run recorded ([[ATTACHMENT|…]]) as visual evidence'
+      help_flag :stamp_all, 'With --junit: put --pr/--work-item on every receipt, not only on tests in files this branch changed'
       help_example 'fp report print_container_qr --project stowzilla --surface api --file spec/qr_spec.rb --repo stowzilla/app'
       help_example 'fp report --junit junit.xml --project stowzilla --surface api --repo stowzilla/app',
                    'Batch-upload from a JUnit report (slugs come from fp:<slug> markers)'
       help_note "Agents report 'present' or 'stub' only. CI writes 'passing'/'failing' via fp ci-report.\n" \
-                'Always pass --test-type when a surface has more than one suite, or they overwrite each other.'
+                "Always pass --test-type when a surface has more than one suite, or they overwrite each other.\n" \
+                'With --junit, --pr and --work-item land only on tests in files this branch changed (git); ' \
+                'the rest of the suite keeps the card and PR that introduced it.'
 
       KNOWN_FLAGS = {
         project: :string,
@@ -58,7 +63,8 @@ module Fp
         state: :string,
         junit: :string,
         base_dir: :string,
-        attach_media: :boolean
+        attach_media: :boolean,
+        stamp_all: :boolean
       }.freeze
 
       VALID_STATES = %w[present stub].freeze
@@ -261,6 +267,12 @@ module Fp
 
         project_id = resolve_project_id(opts[:project])
 
+        # --pr and --work-item say what prompted *this* work. A suite run covers every
+        # marker in the repo, so stamping them on every receipt rewrote the card and PR
+        # on requirements the branch never touched — "View Card" on an unrelated
+        # requirement led to whichever card last ran the suite (Fizzy #1631). Only the
+        # tests in files this branch changed get them; the rest keep their own.
+        provenance = provenance_scope(opts, base_dir)
         reported = []
         skipped_unknown = []
         api_unavailable = false
@@ -289,9 +301,10 @@ module Fp
           }
           params[:test_type] = binding.test_type if binding.test_type
           params[:line] = binding.line if binding.line
-          params[:pr_url] = opts[:pr] if opts[:pr]
+          stamped = provenance.stamps?(binding.file)
+          params[:pr_url] = opts[:pr] if opts[:pr] && stamped
           params[:sha] = opts[:sha] if opts[:sha]
-          params[:work_item_url] = opts[:work_item] if opts[:work_item]
+          params[:work_item_url] = opts[:work_item] if opts[:work_item] && stamped
           params[:ci_url] = opts[:ci_url] if opts[:ci_url]
           params[:title] = binding.title if binding.title
 
@@ -310,7 +323,7 @@ module Fp
             exit 1
           end
 
-          reported << { binding: binding, state: state, recorded: true,
+          reported << { binding: binding, state: state, recorded: true, stamped: stamped,
                         stored_status: stored_status_from(report_result),
                         stored_source: stored_source_from(report_result) }
         end
@@ -321,7 +334,80 @@ module Fp
         end
 
         emit_junit_summary(opts, reported, skipped_unknown, unmatched, api_unavailable, collisions,
-                           empty_name: empty_name, media: media, uploaded_media: uploaded_media)
+                           empty_name: empty_name, media: media, uploaded_media: uploaded_media,
+                           provenance: provenance)
+      end
+
+      # Which receipts of a --junit batch carry --pr/--work-item.
+      #
+      # `files` is the set of repo-relative paths this branch changed — the commits since
+      # it left the default branch, plus anything uncommitted or untracked — or, when
+      # the checkout *is* the default branch, the files in its HEAD commit. Nil means
+      # git couldn't say (not a repository, no default branch to compare with), and then
+      # every receipt is stamped as before, with a note. `--stamp-all` forces that.
+      ProvenanceScope = Struct.new(:mode, :files, keyword_init: true) do
+        def stamps?(file)
+          return true if mode == :all || files.nil?
+
+          files.include?(file.to_s)
+        end
+
+        def scoped?
+          mode != :all && !files.nil?
+        end
+      end
+
+      def provenance_scope(opts, base_dir)
+        return ProvenanceScope.new(mode: :all, files: nil) if opts[:stamp_all]
+        return ProvenanceScope.new(mode: :all, files: nil) if opts[:pr].nil? && opts[:work_item].nil?
+
+        root = Fp::JUnit.repo_root_for(base_dir)
+        return ProvenanceScope.new(mode: :no_git, files: nil) if root.nil?
+
+        head = git_out(root, 'rev-parse', 'HEAD')
+        return ProvenanceScope.new(mode: :no_git, files: nil) if head.nil? || head.empty?
+
+        base = merge_base_with_default_branch(root)
+        committed =
+          if base && base != head
+            git_out(root, 'diff', '--name-only', base, 'HEAD')
+          elsif base
+            # On the default branch itself: the work is whatever this commit touched.
+            git_out(root, 'diff-tree', '--no-commit-id', '--name-only', '-r', '--root', 'HEAD')
+          end
+        return ProvenanceScope.new(mode: :no_git, files: nil) if committed.nil?
+
+        pending = git_out(root, 'diff', '--name-only', 'HEAD') || ''
+        untracked = git_out(root, 'ls-files', '--others', '--exclude-standard') || ''
+        files = [committed, pending, untracked].join("\n").split("\n").map(&:strip).reject(&:empty?).to_set
+        ProvenanceScope.new(mode: (base != head ? :branch : :commit), files: files)
+      end
+
+      # The merge base between HEAD and the default branch, trying origin's HEAD first
+      # and the usual names after it. Nil when none of them exists locally.
+      def merge_base_with_default_branch(root)
+        candidates = []
+        remote_head = git_out(root, 'symbolic-ref', '--short', '-q', 'refs/remotes/origin/HEAD')
+        candidates << remote_head if remote_head && !remote_head.empty?
+        candidates.concat(%w[origin/main origin/master main master])
+        candidates.uniq.each do |ref|
+          verified = git_out(root, 'rev-parse', '--verify', '-q', "#{ref}^{commit}")
+          next if verified.nil? || verified.empty?
+
+          base = git_out(root, 'merge-base', ref, 'HEAD')
+          return base if base && !base.empty?
+        end
+        nil
+      end
+
+      # Stdout of a git command, stripped — '' when it printed nothing, nil on failure.
+      def git_out(root, *args)
+        stdout, _stderr, status = Open3.capture3('git', *args, chdir: root)
+        return nil unless status.success?
+
+        stdout.strip
+      rescue SystemCallError
+        nil
       end
 
       # Upload the media (videos/screenshots) a run recorded for its bound testcases as
@@ -397,10 +483,13 @@ module Fp
       end
 
       def emit_junit_summary(opts, reported, skipped_unknown, unmatched, api_unavailable, collisions = [],
-                             empty_name: [], media: [], uploaded_media: [])
+                             empty_name: [], media: [], uploaded_media: [], provenance: nil)
+        provenance ||= ProvenanceScope.new(mode: :all, files: nil)
+        stamping = !opts[:pr].nil? || !opts[:work_item].nil?
         data = {
           repo: opts[:repo],
-          reported: reported.map { |r| { slug: r[:binding].slug, surface: r[:binding].surface, test_type: r[:binding].test_type, file: r[:binding].file, line: r[:binding].line, state: r[:state], recorded: r[:recorded], stored_status: r[:stored_status], superseded_by_ci: ci_superseded?(r[:state], r[:stored_status], r[:stored_source]) } },
+          reported: reported.map { |r| { slug: r[:binding].slug, surface: r[:binding].surface, test_type: r[:binding].test_type, file: r[:binding].file, line: r[:binding].line, state: r[:state], recorded: r[:recorded], stamped: (stamping ? r[:stamped] != false : nil), stored_status: r[:stored_status], superseded_by_ci: ci_superseded?(r[:state], r[:stored_status], r[:stored_source]) }.compact },
+          provenance: (stamping ? { scoped: provenance.scoped?, mode: provenance.mode.to_s, stamped: reported.count { |r| r[:stamped] != false } } : nil),
           skipped_unknown: skipped_unknown.map { |b| { slug: b.slug, surface: b.surface, file: b.file } },
           unmatched_testcases: unmatched.map { |tc| { name: tc.name, file: tc.file } },
           empty_name: empty_name,
@@ -423,7 +512,21 @@ module Fp
             loc = r[:binding].line ? "#{r[:binding].file}:#{r[:binding].line}" : r[:binding].file
             type = r[:binding].test_type ? " [#{r[:binding].test_type}]" : ''
             shown_state = superseded ? "#{r[:stored_status]}, kept CI — #{r[:state]} ignored" : r[:state]
-            puts "  #{marker} #{r[:binding].slug} → #{r[:binding].surface}#{type}  (#{shown_state})  #{loc}"
+            stamp = stamping && provenance.scoped? && r[:stamped] ? '  ← this change' : ''
+            puts "  #{marker} #{r[:binding].slug} → #{r[:binding].surface}#{type}  (#{shown_state})  #{loc}#{stamp}"
+          end
+
+          if stamping
+            puts
+            stamped = reported.count { |r| r[:stamped] != false }
+            what = [opts[:pr] && '--pr', opts[:work_item] && '--work-item'].compact.join(' and ')
+            if provenance.scoped?
+              where = provenance.mode == :commit ? 'the files in this commit' : 'the files this branch changed'
+              puts "ℹ️  #{what} recorded on #{stamped} of #{reported.length} receipt(s) — the tests in #{where}."
+              puts '    The rest keep the card and PR that introduced them. Pass --stamp-all to override.'
+            elsif provenance.mode == :no_git
+              puts "ℹ️  #{what} recorded on every receipt: git could not say which files this change touched."
+            end
           end
 
           emit_collision_warning(collisions)

data/lib/fp/commands/show.rb

@@ -158,6 +158,21 @@ module Fp
               puts "  #{surface}:"
               records.each do |e|
                 puts "    Status:  #{e['status']}"
+                # 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.
+                if e['merged_status'] && e['merged_status'] != e['status']
+                  puts "    Merged:  #{e['merged_status']} (the default branch's last verdict)"
+                end
+                # An open pull request's CI has reported on this test since the default
+                # branch did. It never changes the status above (Fizzy #1631); it is
+                # the heads-up that a branch says otherwise, with the PR to look at.
+                if e['branch_status']
+                  branch = ["On PR:   #{e['branch_status']}"]
+                  branch << e['branch_pr_url'] if e['branch_pr_url']
+                  branch << '(not merged)'
+                  puts "    #{branch.join(' ')}"
+                end
                 puts "    Type:    #{e['test_type']}" if e['test_type'] && e['test_type'] != 'unspecified'
                 if e['source_file']
                   loc = e['source_line'] ? "#{e['source_file']}:#{e['source_line']}" : e['source_file']

data/lib/fp/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Fp
-  VERSION = '0.0.24'
+  VERSION = '0.0.26'
 end

data/skills/fp/SKILL.md

@@ -336,6 +336,53 @@ This also catches the one regression a green test suite can't: a test that was d
 renamed, or had its `fp:` marker stripped. Every remaining test passes, so CI is happy,
 while the requirement quietly lost its only proof.
 
+**On a pull request, add `--pr`.** A push to the default branch is asked "is the project
+in parity?" — the standing verdict, red until every pending proposal is decided. A pull
+request is asked "does this change make parity worse?": only what the run introduced (a
+bound test gone red, one that vanished, a non-green test added) fails it, and what the
+default branch already owed is listed as "already on the default branch" and not counted.
+So a PR that proposes a removal and deletes the test is not red for a review that hasn't
+happened yet — but one that deletes a test under a *modification* proposal is: a
+modification asks for the test to be rewritten, not removed.
+
+```bash
+fp check --surface api --junit junit.xml --pr "$PR_URL"
+```
+
+**Verifying your own pull request.** Run the PR gate on your branch's JUnit and read three
+things, all in `--json` too:
+
+1. `violations` — regressions you introduced. Must be empty. Each names an `action`.
+2. `improvements` — cells your change fixed (`from` → `to`). The requirement you set out
+   to cover should be here (or already `passing`).
+3. `unmeasured` — your results bound to **draft** requirements. A test for a requirement
+   you proposed lands here until a human activates it; that is expected, not a gap.
+
+`inherited_violations` are the default branch's, not yours. Leave them unless you were
+asked to clear them.
+
+**Bringing the default branch up to parity.** When asked (or on a schedule), run the
+standing gate and work the list the server hands back:
+
+```bash
+fp check --json      # violations[*].action / .owner / .action_hint
+```
+
+Take every violation whose `owner` is `agent`, grouped by `action`:
+
+| action | what to do |
+|--------|------------|
+| `write_test` | write a test on that surface, mark it `fp:<slug>`, `fp report` it |
+| `fix_test` | fix the red test — or, if the feature was removed on purpose, `fp propose-change <slug> --removal` |
+| `replace_stub` | replace the stub with a real test |
+| `run_in_ci` | the marker exists but CI never ran it green: make sure the test runs in a CI job that calls `fp ci-report` for that surface |
+| `reverify` | the wording changed with no proposal open: check the test still proves it, fix it if not, re-report to clear `suspect` |
+| `fix_marker` | an orphan marker: fix the slug, or `fp propose` the requirement |
+
+Leave `owner: human` rows alone — `await_review` is a proposal a person has to decide,
+`await_merge` is a pull request a person has to merge — and say so in your report. Open one
+pull request per coherent batch, gate it with `--pr`, and re-run `fp check` after it merges.
+
 ### 9. Fill in the client showroom when a surface is deployed
 
 The project's client (the person the software is being built for) sees one page: the

data/skills/fp/references/cli.md

@@ -526,6 +526,7 @@ fp check --surface api --junit junit.xml  # gate on this run's results (preview)
 | `--surface` | Gate one surface only |
 | `--level` | Override the project's enforcement level |
 | `--junit` | Evaluate this run's JUnit results without saving them (repeatable) |
+| `--pr [url]` | With `--junit`: this run is a pull request — fail only on parity it makes worse |
 | `--warn-only` | Report violations but exit 0 |
 
 **Enforcement levels** (the level is configured on the project; don't hardcode one):
@@ -567,6 +568,48 @@ while the requirement silently lost its only proof. Pass one `--junit` per surfa
 `--surface` tells the server which cells the run had a chance to cover, and pooling
 surfaces into one call would misattribute vanished tests.
 
+**Pull-request mode (`--pr`).** A push to the default branch asks "is the project in
+parity?" — the standing verdict, red until every pending proposal is decided and every
+gap filled. A pull request should be asked "does this change make parity worse?". With
+`--pr` (and `--junit`) the run is judged against what the default branch has recorded and
+only what it *introduced* fails: a bound test gone red, a bound test that vanished, a
+non-green test added where there was none. What the default branch already owed is listed
+as "already on the default branch" and not counted, so a PR that proposes a requirement's
+removal and deletes its test is not red for the removal nobody has approved yet. Without
+`--pr`, every PR on a `strict` project failed with master's own standing violations.
+
+```
+3 violation(s) already on the default branch (not counted against this change):
+  SLUG                SURFACE  STATE      WHY
+  retire_old_heading  api      ⚠ suspect  requirement changed; evidence needs re-verification
+Gate passed: this change introduces no parity regressions. 3 violation(s) already on the default branch are not counted here.
+```
+
+A deleted bound test is only excused by a *removal* proposal. Under a modification
+proposal (or a human's direct edit) the evidence is `suspect`, and a `suspect` test
+missing from the run is flagged like a passing one that vanished — the proposal asked
+for the test to be rewritten, not removed.
+
+The PR verdict also lists what the change *fixed* (cells violating on the default branch,
+green with the run applied) and results bound to *draft* requirements the gate doesn't
+measure until a human activates them. In `--json`: `improvements`, `unmeasured`. Orphan
+markers the default branch's last run already recorded are listed as "already on the
+default branch" and never fail the PR; only orphans the run added count.
+
+**Next steps.** Every verdict ends with the violations that count, grouped by who acts.
+Each violation in `--json` carries `action`, `owner` (`agent` | `human`) and `action_hint`:
+
+| action | owner | means |
+|--------|-------|-------|
+| `write_test` | agent | `missing` — no evidence on this surface |
+| `fix_test` | agent | `failing` — red, or the marker vanished; or propose removal |
+| `replace_stub` | agent | `stub` — a stub stands where a real test should |
+| `run_in_ci` | agent | `present` — the marker exists but CI has never run it green |
+| `reverify` | agent | `suspect` with no proposal open — the wording changed; re-check and re-report |
+| `await_review` | human | `suspect` under an open proposal |
+| `await_merge` | human | `pr_passing` — green on an open pull request |
+| `fix_marker` | agent | an orphan marker — fix the slug or propose the requirement |
+
 ### fp init
 
 Onboard a repo onto FeatureParity. Writes three files and makes no API calls (so it works

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: featureparity
 version: !ruby/object:Gem::Version
-  version: 0.0.24
+  version: 0.0.26
 platform: ruby
 authors:
 - Stowzilla
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-10-21 00:00:00.000000000 Z
+date: 2026-10-27 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: net-http