featureparity 0.0.24 → 0.0.25

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4e68b70dce16d28e928ead4413623002ccda97f4508f62bbe6d980c8bb29a21c
-  data.tar.gz: e630a9bd6f49db70c343f6374cd3c049a9c9fb4b786251dd313b76a177e0a1f9
+  metadata.gz: a7a4558cdeaa90d0b4197daca351b9eadbeee5af21cb8454e9a1f44b3725bbaa
+  data.tar.gz: d0134aeca43dd6ee3415bfafe25ea7f67212eda1b8577a3bdfd9d9a3800aa150
 SHA512:
-  metadata.gz: 55bde2507b4cfccbe49b8d799d0b3e7efba22c0298450e823a3ac86299ec4d392b0e51f13c3c643a2abc1d60f1d68d091074420c0928fbbcf9da6947fea296d1
-  data.tar.gz: c5d9754313a59721bfc78f5d4e65d4924ef1f5120659037cace19e6ee816a96dea0e467f47ad285cf03003ba37ed836501754c5592f9b22385f5a52315be5cae
+  metadata.gz: 70827aadfd85037c992e670923ae4c7065c6ba913905028b903f4b6535f8498f530d3ec51a9ff245aa9734a3f044d6ca779b5e8b849b0a15d1b6b2aaed360e2f
+  data.tar.gz: 9ba46d5f8efa5a57e4b23c2557969cdd5c6b6697cb8584bb98b7c11fc237a099743c33474b46d05444361785278707981206af09e7c32570261ae5b104a9885d

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)
       body = {
         ci_url: ci_url,
         surface: surface,
@@ -296,6 +296,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 +353,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
 
@@ -142,7 +148,10 @@ module Fp
           pr_url: opts[:pr],
           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 +270,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/show.rb

@@ -158,6 +158,12 @@ 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
                 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.25'
 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.25
 platform: ruby
 authors:
 - Stowzilla
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-10-21 00:00:00.000000000 Z
+date: 2026-10-23 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: net-http