featureparity 0.0.16 → 0.0.17

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: dd15c5892d88c0202433fd6e11993440f45cd3cb8c754c0c7138309008190cbb
-  data.tar.gz: 356c8c54af360a47639e2dfc6313774247ff93534eb02b6666656f738d69ce70
+  metadata.gz: d20b326add84bbad1fc34a9b2b41c70216f7e9f2797f47cc9cba9f4293d27f1e
+  data.tar.gz: ae9721b86841174ee64f1925b0878e5ca5b5e34ea1f467ea0275887526515695
 SHA512:
-  metadata.gz: d0d96204c4cf14ff9c7f5bbf1930f1ad6f170b11be67651df1cda342c2ad41e53e1a09ea93bed84db620d2c867f26ffbc313fa2d132f7b5b8b474026b4ea9ee8
-  data.tar.gz: c43e169274e9c6484b6e41c2bcb1c5748eaee9dabad8c39f523c7ed30a08f0edaeae3df7637edc799d2089165624108e72fdb517c95d580cc51c1b747064726b
+  metadata.gz: 87aa7b100433761979acec4c6a3f66c665757ebd77924cf1bab483861a1855be92acba93d3a6bd0e2f0cdc9daf9c887380a808eab96c467c3a41ee4e665f8bb0
+  data.tar.gz: 640c69700985e08ce0c6aec534d42d544db0d04771ae9f9be254e24aca3952cbbff7f52456c1c7b506c8bbf5e6a3d3b54c8c7959d6575d159d19cff5cad69c0b

data/lib/fp/cli.rb

@@ -11,10 +11,12 @@ module Fp
       'show' => Commands::Show,
       'propose' => Commands::Propose,
       'propose-change' => Commands::ProposeChange,
+      'comment' => Commands::Comment,
       'history' => Commands::History,
       'changes' => Commands::Changes,
       'report' => Commands::Report,
       'ci-report' => Commands::CiReport,
+      'changed-tests' => Commands::ChangedTests,
       'check' => Commands::Check,
       'matrix' => Commands::Matrix,
       'export' => Commands::Export,

data/lib/fp/client.rb

@@ -130,6 +130,15 @@ module Fp
       put("/api/requirements/#{requirement_id}/changes/#{change_id}", params)
     end
 
+    # POST /requirements/:id/changes/:change_id/comment
+    #
+    # Thread a comment onto the open proposal. The single-open-proposal rule means a
+    # second agent can't open a rival change; this lets it raise its concern *on* the
+    # proposal a human is about to review instead of hitting a dead-end 409.
+    def comment_requirement_change(requirement_id, change_id, params)
+      post("/api/requirements/#{requirement_id}/changes/#{change_id}/comment", params)
+    end
+
     # GET /projects/:project_id/evidence — the receipts already filed for a project,
     # optionally narrowed to one requirement slug and/or surface.
     def list_evidence(project_id, slug: nil, surface: nil)
@@ -160,7 +169,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,
-                          unmarked_failures: nil)
+                          test_revisions: nil, unmarked_failures: nil)
       body = {
         ci_url: ci_url,
         surface: surface,
@@ -169,6 +178,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?
       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.
+      body[:test_revisions] = test_revisions if test_revisions && !test_revisions.empty?
       # 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?
@@ -176,6 +188,27 @@ module Fp
       post("/api/projects/#{project_id}/ci_results", body)
     end
 
+    # GET /projects/:project_id/changed_test_findings — every unresolved audit finding.
+    def list_changed_test_findings(project_id, surface: nil, test_type: nil)
+      params = {}
+      params[:surface] = surface if surface
+      params[:test_type] = test_type if test_type
+      get("/api/projects/#{project_id}/changed_test_findings", params)
+    end
+
+    # POST an assessment for the exact candidate fingerprint the agent inspected.
+    def assess_changed_test_finding(project_id, finding_id, classification:, explanation:,
+                                    candidate_fingerprint:)
+      post(
+        "/api/projects/#{project_id}/changed_test_findings/#{finding_id}/assessment",
+        {
+          classification: classification,
+          explanation: explanation,
+          candidate_fingerprint: candidate_fingerprint
+        }
+      )
+    end
+
     # GET /projects/:project_id/parity — the computed parity grid and gate verdict.
     #
     # This replaces the old get_matrix/get_gaps stubs, which pointed at /api/matrix
@@ -205,7 +238,10 @@ module Fp
     # 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)
-      body = { surface: surface, junit_xmls: Array(junit_xmls) }
+      # 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
       post("/api/projects/#{project_id}/parity/preview", body)
@@ -360,7 +396,11 @@ module Fp
                         else
                           body.to_s.empty? ? "HTTP #{status}" : body.to_s[0..200]
                         end
-        { ok: false, error: error_message, status: status }
+        result = { ok: false, error: error_message, status: status }
+        # Carry structured error details (e.g. the open proposal behind a 409) so a
+        # command can act on them instead of only printing the message.
+        result[:details] = data['details'] if data.is_a?(Hash) && data.key?('details')
+        result
       end
     end
   end

data/lib/fp/commands/changed_tests.rb

@@ -0,0 +1,126 @@
+# frozen_string_literal: true
+
+module Fp
+  module Commands
+    # Lists CI-detected revisions to bound tests and records an agent's assessment of an
+    # exact candidate fingerprint.
+    class ChangedTests < Base
+      CLASSIFICATIONS = %w[still_proves no_longer_proves uncertain].freeze
+      KNOWN_FLAGS = {
+        project: :string,
+        surface: :string,
+        test_type: :string,
+        classification: :string,
+        explanation: :string,
+        candidate_fingerprint: :string
+      }.freeze
+
+      def run(args)
+        opts, positional = parse_flags(args, KNOWN_FLAGS)
+        require_project!(opts)
+        project_id = resolve_project_id(opts[:project])
+
+        if positional.first == 'assess'
+          assess(project_id, positional[1], opts)
+        else
+          list(project_id, opts)
+        end
+      end
+
+      private
+
+      def list(project_id, opts)
+        result = client.list_changed_test_findings(
+          project_id,
+          surface: opts[:surface],
+          test_type: opts[:test_type]
+        )
+        fail_result(result) unless result[:ok]
+
+        data = result[:data] || {}
+        findings = data['changed_test_findings'] || []
+        output.success(data) do
+          if findings.empty?
+            puts 'No unresolved changed-test findings.'
+            next
+          end
+
+          puts "#{findings.length} unresolved changed-test audit finding(s):"
+          findings.each { |finding| print_finding(finding) }
+        end
+      end
+
+      def assess(project_id, finding_id, opts)
+        if finding_id.nil? || finding_id.empty?
+          output.error('Finding id is required. Usage: fp changed-tests assess <id> ...')
+          exit 1
+        end
+
+        classification = opts[:classification].to_s.tr('-', '_')
+        unless CLASSIFICATIONS.include?(classification)
+          output.error("--classification must be one of: #{CLASSIFICATIONS.join(', ')}")
+          exit 1
+        end
+        require_flag(opts, :candidate_fingerprint)
+        require_flag(opts, :explanation)
+        if opts[:explanation].to_s.strip.empty?
+          output.error('--explanation must not be blank')
+          exit 1
+        end
+
+        result = client.assess_changed_test_finding(
+          project_id,
+          finding_id,
+          classification: classification,
+          explanation: opts[:explanation],
+          candidate_fingerprint: opts[:candidate_fingerprint]
+        )
+        fail_result(result) unless result[:ok]
+
+        data = result[:data] || {}
+        output.success(data) do
+          finding = data['changed_test_finding'] || {}
+          puts "Recorded #{classification.tr('_', ' ')} for changed-test finding #{finding_id}."
+          puts "Status: #{finding['status']}"
+          puts 'The CI outcome and requirement wording were not changed.'
+        end
+      end
+
+      def print_finding(finding)
+        requirement = finding['requirement'] || {}
+        testcase = finding['testcase'] || {}
+        accepted = finding['accepted'] || {}
+        candidate = finding['candidate'] || {}
+        assessment = finding['assessment'] || {}
+
+        puts
+        puts "#{finding['id']}  #{requirement['slug']}  [#{finding['surface']}#{type_suffix(finding)}]"
+        puts "  Requirement: #{requirement['title']}"
+        puts "  Acceptance:  #{requirement['acceptance']}"
+        puts "  Testcase:    #{testcase['name']} (#{testcase['outcome']})"
+        puts "  Scope:       #{finding['fingerprint_scope']}"
+        puts "  Accepted:    #{revision_text(accepted)}"
+        puts "  Candidate:   #{revision_text(candidate)}"
+        puts "  Assessment:  #{assessment['classification']}: #{assessment['explanation']}" unless assessment.empty?
+        puts '  Assess:      fp changed-tests assess ' \
+             "#{finding['id']} --candidate-fingerprint #{candidate['fingerprint']} " \
+             '--classification still_proves|no_longer_proves|uncertain --explanation "..."'
+      end
+
+      def type_suffix(finding)
+        type = finding['test_type'].to_s
+        type.empty? || type == 'unspecified' ? '' : ":#{type}"
+      end
+
+      def revision_text(revision)
+        location = revision['source_url'] || [revision['source_file'], revision['start_line']].compact.join(':')
+        "#{revision['fingerprint']} @ #{revision['commit_sha']} #{location}".strip
+      end
+
+      def fail_result(result)
+        output.error(result[:error], status: result[:status])
+        exit 1
+      end
+    end
+  end
+end

data/lib/fp/commands/ci_report.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require 'set'
+require 'open3'
 
 module Fp
   module Commands
@@ -34,8 +35,10 @@ module Fp
     # `fp report`.
     #
     # Multiple --junit flags may be passed to ingest several reports for the same
-    # surface in one invocation (e.g. a suite split across shards). Each is
-    # uploaded in turn.
+    # surface in one invocation (e.g. unit and e2e suites, or test shards). They are
+    # resolved and uploaded as one run. This is load-bearing: each API ingest performs
+    # the vanished-test sweep, so uploading partitions independently would make every
+    # partition call the passing tests in its siblings "missing".
     #
     # --base-dir tells the CLI where the report's relative test-file paths resolve from
     # (vitest, for instance, reports paths relative to the frontend package, not the repo
@@ -55,6 +58,8 @@ module Fp
         pr: :string,
         junit: :string,
         base_dir: :string,
+        repo: :string,
+        sha: :string,
         allow_empty: :boolean
       }.freeze
 
@@ -81,42 +86,64 @@ module Fp
 
         project_id = resolve_project_id(opts[:project])
         known = known_slugs(project_id)
+        commit_sha = resolve_commit_sha(opts)
+        repo = opts[:repo] || presence(ENV['GITHUB_REPOSITORY'])
 
         totals = { created: 0, updated: 0, missing_failing: 0, reports: [], resolved: 0,
-                   unmatched: 0, unknown: [], unmarked_failures: [] }
+                   unmatched: 0, unknown: [], unmarked_failures: [], test_revisions: 0,
+                   findings_opened: 0, baselines_accepted: 0 }
 
-        junit_paths.each do |path|
-          xml = File.read(path)
-          resolved = resolve_results(path, opts)
+        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)
           totals[:resolved] += results.length
-          totals[:unknown].concat(unknown)
+          totals[:unknown].concat(unknown).concat(revision_unknown)
           totals[:unmarked_failures].concat(resolved[:unmarked_failures])
+          totals[:test_revisions] += test_revisions.length
 
-          result = client.ingest_ci_results(
-            project_id,
-            ci_url: opts[:ci_url],
-            surface: opts[:surface],
-            junit_xml: xml,
-            pr_url: opts[:pr],
-            results: results,
-            unmarked_failures: resolved[:unmarked_failures]
-          )
-
-          unless result[:ok]
-            output.error("Failed to ingest #{path}: #{result[:error]}", status: result[:status])
-            exit 1
-          end
+          { path: path, xml: File.read(path), results: results, test_revisions: test_revisions }
+        end
+
+        # One surface run may be split across several reports (unit + e2e, shards, etc.).
+        # The API's vanished-test sweep must see their union in one request; posting each
+        # partition separately makes the tests in every sibling report appear to have
+        # disappeared. Duplicate slug/surface/type claims are collapsed conservatively.
+        combined_results = combine_results(resolved_reports.flat_map { |report| report[:results] })
+        combined_revisions = combine_test_revisions(
+          resolved_reports.flat_map { |report| report[:test_revisions] }
+        )
+        result = client.ingest_ci_results(
+          project_id,
+          ci_url: opts[:ci_url],
+          surface: opts[:surface],
+          # Resolved results are authoritative. Keep one valid raw report for compatibility
+          # with servers old enough to ignore client-resolved results.
+          junit_xml: resolved_reports.first[:xml],
+          pr_url: opts[:pr],
+          results: combined_results,
+          test_revisions: combined_revisions,
+          unmarked_failures: totals[:unmarked_failures]
+        )
 
-          data = result[:data] || {}
-          totals[:created] += data['evidence_created'].to_i
-          totals[:updated] += data['evidence_updated'].to_i
-          totals[:missing_failing] += data['missing_marked_failing'].to_i
-          totals[:reports] << { path: path, results: data['results'] || [] }
+        unless result[:ok]
+          output.error("Failed to ingest #{junit_paths.join(', ')}: #{result[:error]}", status: result[:status])
+          exit 1
         end
 
+        data = result[:data] || {}
+        # Belt's implicit instance-variable serializer wrapped this response in older
+        # deployments. Accept both shapes while the API now returns the result directly.
+        data = data['ingest_result'] if data['ingest_result'].is_a?(Hash)
+        totals[:created] += data['evidence_created'].to_i
+        totals[:updated] += data['evidence_updated'].to_i
+        totals[:missing_failing] += data['missing_marked_failing'].to_i
+        totals[:findings_opened] += data['changed_test_findings_opened'].to_i
+        totals[:baselines_accepted] += data['bound_test_baselines_accepted'].to_i
+        totals[:reports] << { paths: junit_paths, results: data['results'] || [] }
+
         # Reporting nothing is the failure this command exists to make visible: a run that
         # resolves no markers has told the matrix nothing, and used to do so silently.
         if totals[:resolved].zero? && !opts[:allow_empty]
@@ -194,6 +221,29 @@ module Fp
         (result[:data]['requirements'] || []).map { |r| r['slug'] }.compact.to_set
       end
 
+      # Collapse the same marker key across report partitions before uploading it. A red
+      # claim wins; otherwise any executed passing test wins over an all-skipped stub.
+      # Counts are summed so the evidence still describes the complete surface run, and
+      # the source points at the claim that determined the verdict.
+      def combine_results(results)
+        severity = { 'failing' => 0, 'passing' => 1, 'stub' => 2 }
+
+        results.each_with_object({}) do |result, combined|
+          key = [result[:slug], result[:surface], result[:test_type]]
+          current = combined[key]
+          unless current
+            combined[key] = result.dup
+            next
+          end
+
+          decisive = [current, result].min_by { |entry| severity.fetch(entry[:status], 0) }
+          merged = decisive.dup
+          merged[:test_count] = current[:test_count].to_i + result[:test_count].to_i
+          merged[:failure_count] = current[:failure_count].to_i + result[:failure_count].to_i
+          combined[key] = merged
+        end.values
+      end
+
       def partition_known(results, known)
         return [results, []] if known.nil?
 
@@ -201,6 +251,15 @@ module Fp
         [kept, unknown.map { |r| r[:slug] }.uniq]
       end
 
+      # Reports can be split into shards. Keep every independently identified testcase,
+      # but collapse an exact duplicate emitted by overlapping reports.
+      def combine_test_revisions(revisions)
+        revisions.each_with_object({}) do |revision, combined|
+          key = [revision[:slug], revision[:surface], revision[:test_type], revision[:testcase_key]]
+          combined[key] = revision
+        end.values
+      end
+
       # A warning that survives a CI log. Stderr always; a GitHub Actions annotation too
       # when we're running in one, so it shows up in the run summary rather than scrolling
       # past in a collapsed step.
@@ -210,13 +269,15 @@ module Fp
       end
 
       # Bind this report's testcases to their fp markers, locally, in the checkout.
-      def resolve_results(path, opts)
+      def resolve_results(path, opts, commit_sha:, repo:)
         testcases = Fp::JUnit.parse_file(path)
         resolved = Fp::JUnit.ci_results(
           testcases,
           base_dir: opts[:base_dir] || Dir.pwd,
           default_surface: opts[:surface],
-          default_test_type: opts[:test_type]
+          default_test_type: opts[:test_type],
+          commit_sha: commit_sha,
+          repo: repo
         )
 
         {
@@ -233,6 +294,25 @@ module Fp
               failure_count: r.failure_count
             }
           end,
+          test_revisions: resolved[:test_revisions].map do |revision|
+            {
+              slug: revision.slug,
+              surface: revision.surface,
+              test_type: revision.test_type,
+              testcase_key: revision.testcase_key,
+              testcase_name: revision.testcase_name,
+              classname: revision.classname,
+              outcome: revision.outcome,
+              repo: revision.repo,
+              source_file: revision.file,
+              marker_line: revision.marker_line,
+              source_start_line: revision.start_line,
+              source_end_line: revision.end_line,
+              commit_sha: revision.commit_sha,
+              fingerprint: revision.fingerprint,
+              fingerprint_scope: revision.fingerprint_scope
+            }
+          end,
           unmatched: resolved[:unmatched].length,
           # Loose ends: failing tests with no fp:<slug> marker. Shipped to the server so a
           # human can see them on the matrix; a red test nobody tracks against a
@@ -251,6 +331,27 @@ module Fp
         exit 1
       end
 
+      def resolve_commit_sha(opts)
+        explicit = presence(opts[:sha])
+        return explicit if explicit
+
+        root = Fp::JUnit.repo_root_for(opts[:base_dir] || Dir.pwd)
+        stdout, _stderr, status = Open3.capture3('git', 'rev-parse', 'HEAD', chdir: root || Dir.pwd)
+        sha = presence(stdout)
+        return sha if status.success? && sha
+
+        ci_sha = presence(ENV['GITHUB_SHA'])
+        return ci_sha if ci_sha
+
+        output.error('Could not determine the tested commit. Pass --sha <commit>.')
+        exit 1
+      end
+
+      def presence(value)
+        text = value.to_s.strip
+        text.empty? ? nil : text
+      end
+
       # Pull the human-readable summary together. `markers_resolved` is worth printing
       # even when everything worked: it's the number that used to silently be zero.
       def emit_summary(opts, totals)
@@ -265,6 +366,9 @@ module Fp
           markers_resolved: totals[:resolved],
           unmatched_testcases: totals[:unmatched],
           unmarked_failures: totals[:unmarked_failures],
+          test_revisions_reported: totals[:test_revisions],
+          changed_test_findings_opened: totals[:findings_opened],
+          bound_test_baselines_accepted: totals[:baselines_accepted],
           skipped_unknown: totals[:unknown].uniq,
           reports: totals[:reports]
         }
@@ -288,6 +392,7 @@ module Fp
             puts "  loose ends: #{totals[:unmarked_failures].length} failing test(s) with no " \
                  'fp:<slug> marker (shown on the matrix, not a gate failure)'
           end
+          puts "  source receipts: #{totals[:test_revisions]}   changed-test findings opened: #{totals[:findings_opened]}"
           puts "  created: #{totals[:created]}   updated: #{totals[:updated]}   marked failing (missing): #{totals[:missing_failing]}"
         end
       end

data/lib/fp/commands/comment.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+module Fp
+  module Commands
+    # `fp comment <slug> --body "..."` — thread a comment onto a requirement's open
+    # change proposal.
+    #
+    # The single-open-proposal rule stops a second agent opening a rival change (two
+    # "what it was" snapshots would make a rollback ambiguous). This is the way out of
+    # that dead end: instead of a rival proposal, an agent states its case *on* the
+    # proposal a human is about to review. The comment is append-only — it never touches
+    # the requirement's status or the proposal's snapshot — so the invariant the 409
+    # protects stays intact.
+    class Comment < Base
+      KNOWN_FLAGS = {
+        project: :string, body: :string, change: :string,
+        source_type: :string, source_url: :string, source_context: :string
+      }.freeze
+
+      VALID_SOURCE_TYPES = %w[fizzy discord github_issue jira notion manual ai_chat].freeze
+
+      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 comment <slug> --body "..." [--project <project>]')
+          exit 1
+        end
+
+        body = opts[:body]
+        if body.nil? || body.strip.empty?
+          output.error('A comment body is required. Pass --body "...".')
+          exit 1
+        end
+
+        validate_source_type!(opts)
+
+        project_id = resolve_project_id(opts[:project])
+        requirement = find_requirement!(project_id, slug)
+
+        change_id = opts[:change] || requirement['pending_change_id']
+        if change_id.nil? || change_id.to_s.empty?
+          output.error("Requirement '#{slug}' has no open proposal to comment on.")
+          exit 1
+        end
+
+        result = client.comment_requirement_change(requirement['id'], change_id, build_params(opts))
+        unless result[:ok]
+          output.error(result[:error], status: result[:status])
+          exit 1
+        end
+
+        print_result(result[:data], slug: slug)
+      end
+
+      private
+
+      def validate_source_type!(opts)
+        return unless opts[:source_type] && !VALID_SOURCE_TYPES.include?(opts[:source_type])
+
+        output.error("Invalid source type '#{opts[:source_type]}'. Must be one of: #{VALID_SOURCE_TYPES.join(', ')}")
+        exit 1
+      end
+
+      def find_requirement!(project_id, slug)
+        result = client.find_requirement_by_slug(project_id, slug)
+        unless result[:ok]
+          output.error(result[:error], status: result[:status])
+          exit 1
+        end
+        result[:data]['requirement']
+      end
+
+      def build_params(opts)
+        params = { body: opts[:body] }
+        params[:source_type] = opts[:source_type] if opts[:source_type]
+        params[:source_url] = opts[:source_url] if opts[:source_url]
+        params[:source_context] = opts[:source_context] if opts[:source_context]
+        params
+      end
+
+      def print_result(data, slug:)
+        change = data['change'] || {}
+
+        output.success(data) do
+          puts "Commented on the open proposal for '#{slug}'."
+          puts
+          puts "  Comment:  #{change['body']}"
+          puts "  On:       #{change['proposal_id']}"
+          puts
+          puts 'A human reviewing the proposal will see this comment in the history.'
+          puts "Run `fp history #{slug} --project <project>` to see the thread."
+        end
+      end
+    end
+  end
+end

data/lib/fp/commands/help.rb

@@ -22,6 +22,7 @@ module Fp
             propose --project <slug> ...      Propose a new requirement (as draft)
             propose-change <slug> ...         Propose a change to an existing requirement
             propose-change <slug> --removal   Propose deleting a requirement
+            comment <slug> --body "..."       Comment on a requirement's open change proposal
             history <slug> --project <slug>   Show a requirement's change history + diffs
             changes [--source-url URL] [--github-pr]  Show or publish work-item-linked activity
             attach <slug> <file>              Upload a file attachment to a requirement
@@ -33,6 +34,8 @@ module Fp
             report --junit <file> ...         Upload evidence from a JUnit XML report (no CI)
             ci-report --junit <file> ...      Ingest CI test results (passing/failing) — CI only
             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
             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
@@ -77,6 +80,24 @@ module Fp
             merged-green truth. Run ci-report *without* --pr on a push to the default branch to
             record the real `passing`, which supersedes any pr_passing a prior PR left behind.
 
+          CHANGED BOUND TESTS
+            `fp ci-report` fingerprints every bound testcase at the checkout commit. It uses
+            an isolated-test SHA-256 when the source boundary is reliable and labels a whole-file
+            fallback otherwise. A different digest opens an audit finding without turning a green
+            test red or replacing the accepted baseline.
+
+              fp changed-tests
+              fp changed-tests --json
+              fp changed-tests assess <finding-id> \
+                --candidate-fingerprint <sha256> \
+                --classification still_proves \
+                --explanation "The setup changed; the same observable result is asserted."
+
+            Classifications are still_proves, no_longer_proves, and uncertain. Only still_proves
+            resolves that exact fingerprint; the other two remain open for a human product decision.
+            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.
+
           AUTHENTICATION
             Set FP_API_KEY environment variable, or use a profile:
 
@@ -175,6 +196,18 @@ module Fp
             # which promise reflects product intent and record that decision with propose-change
             # (or --removal). Never weaken the test or add a requirement around the conflict;
             # ask a human if intent is unclear.
+            # Existing tests are protected product evidence. Flag any edit to a test backing
+            # passing evidence and get explicit human approval before changing its expected
+            # behaviour. When FeatureParity reports a changed bound test, run `fp changed-tests`
+            # (or add `--json`), compare the accepted and candidate revisions with the requirement,
+            # then assess the exact candidate fingerprint with a plain-language explanation as
+            # `still_proves`, `no_longer_proves`, or `uncertain`. Only still_proves resolves that
+            # fingerprint; possible behaviour changes remain open for a human decision, and a later
+            # digest needs a new assessment. This audit finding is separate from the CI outcome and
+            # from `suspect`, which means the requirement wording changed.
+            # A new requirement — draft or active — does not supersede a pre-existing failing test;
+            # surface the conflict and do not change or adopt that test as proof without explicit
+            # human approval.
             #
             # Write the requirement as a product decision someone can approve, not a design
             # task. It should sound like a capable teammate, not AI boilerplate.