featureparity 0.0.16 → 0.0.18

data/lib/fp/commands/report.rb

@@ -86,7 +86,7 @@ module Fp
         params[:work_item_url] = opts[:work_item] if opts[:work_item]
         params[:ci_url] = opts[:ci_url] if opts[:ci_url]
         params[:title] = opts[:title] if opts[:title]
-        params[:line] = opts[:line] if opts[:line]
+        params[:line] = opts[:line].to_i if opts[:line]
 
         # Try to report evidence
         result = client.report_evidence(params)
@@ -115,9 +115,26 @@ module Fp
           exit 1
         end
 
+        # The server echoes back the stored record, whose status/source may differ
+        # from what we asked for: CI evidence is authoritative, so an agent's
+        # present/stub never downgrades a cell CI already verified. Report the truth
+        # the server kept, not the state we requested, so the caller knows whether
+        # their report actually landed or was superseded by CI.
+        stored = result[:data].is_a?(Hash) ? (result[:data]['evidence'] || {}) : {}
+        stored_status = stored['status']
+        stored_source = stored['source']
+        superseded = ci_superseded?(state, stored_status, stored_source)
+
         output.success(result[:data]) do
-          puts "Evidence reported for '#{slug}' on surface '#{opts[:surface]}'."
-          puts "  State: #{state}"
+          if superseded
+            puts "CI already verified '#{slug}' on surface '#{opts[:surface]}' (status: #{stored_status})."
+            puts "Your '#{state}' report was recorded as metadata but did NOT change the status —"
+            puts 'CI evidence is authoritative and is never downgraded by an agent report.'
+            puts '  Stored: ' + "#{stored_status} (source: #{stored_source})"
+          else
+            puts "Evidence reported for '#{slug}' on surface '#{opts[:surface]}'."
+            puts "  State: #{stored_status || state}"
+          end
           puts "  Type:  #{opts[:test_type]}" if opts[:test_type]
           puts "  File:  #{opts[:file]}#{opts[:line] ? ":#{opts[:line]}" : ''}"
           if opts[:pr]
@@ -140,6 +157,20 @@ module Fp
 
       private
 
+      # CI statuses an agent can never set. Mirrors Evidence::CI_STATUSES on the
+      # server — kept here so the CLI can recognise, from the echoed record, when its
+      # present/stub report was superseded by an authoritative CI verdict.
+      CI_STATUSES = %w[passing pr_passing failing].freeze
+
+      # True when the server kept a CI verdict instead of applying our report: the
+      # stored evidence is CI-sourced with a CI status, yet we asked for present/stub.
+      def ci_superseded?(requested_state, stored_status, stored_source)
+        return false if stored_status.nil?
+        return false unless VALID_STATES.include?(requested_state)
+
+        stored_source == 'ci' && CI_STATUSES.include?(stored_status) && stored_status != requested_state
+      end
+
       # Batch-upload evidence from a JUnit XML report.
       def run_junit(opts)
         require_project!(opts)
@@ -244,16 +275,34 @@ module Fp
             exit 1
           end
 
-          reported << { binding: binding, state: state, recorded: true }
+          reported << { binding: binding, state: state, recorded: true,
+                        stored_status: stored_status_from(report_result),
+                        stored_source: stored_source_from(report_result) }
         end
 
         emit_junit_summary(opts, reported, skipped_unknown, unmatched, api_unavailable)
       end
 
+      # Pull the stored status/source out of the server's echoed evidence record so the
+      # batch summary can flag cells where CI superseded the agent's present/stub.
+      def stored_status_from(report_result)
+        data = report_result[:data]
+        return nil unless data.is_a?(Hash)
+
+        (data['evidence'] || {})['status']
+      end
+
+      def stored_source_from(report_result)
+        data = report_result[:data]
+        return nil unless data.is_a?(Hash)
+
+        (data['evidence'] || {})['source']
+      end
+
       def emit_junit_summary(opts, reported, skipped_unknown, unmatched, api_unavailable)
         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] } },
+          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]) } },
           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 } }
         }
@@ -261,10 +310,18 @@ module Fp
         output.success(data) do
           puts "Reported evidence from #{opts[:junit]}:"
           reported.each do |r|
-            marker = r[:recorded] ? '✓' : '•'
+            superseded = ci_superseded?(r[:state], r[:stored_status], r[:stored_source])
+            marker = if !r[:recorded]
+                       '•'
+                     elsif superseded
+                       '⊘'
+                     else
+                       '✓'
+                     end
             loc = r[:binding].line ? "#{r[:binding].file}:#{r[:binding].line}" : r[:binding].file
             type = r[:binding].test_type ? " [#{r[:binding].test_type}]" : ''
-            puts "  #{marker} #{r[:binding].slug} → #{r[:binding].surface}#{type}  (#{r[:state]})  #{loc}"
+            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}"
           end
 
           unless skipped_unknown.empty?

data/lib/fp/commands.rb

@@ -7,10 +7,13 @@ require_relative 'commands/list'
 require_relative 'commands/show'
 require_relative 'commands/propose'
 require_relative 'commands/propose_change'
+require_relative 'commands/comment'
 require_relative 'commands/history'
+require_relative 'commands/analyze'
 require_relative 'commands/changes'
 require_relative 'commands/report'
 require_relative 'commands/ci_report'
+require_relative 'commands/changed_tests'
 require_relative 'commands/check'
 require_relative 'commands/init'
 require_relative 'commands/matrix'

data/lib/fp/junit.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require 'rexml/document'
+require_relative 'source_fingerprint'
 
 module Fp
   # Parses JUnit XML reports and binds testcases to fp:<slug> markers found in
@@ -40,6 +41,15 @@ module Fp
     CiResult = Struct.new(:slug, :surface, :test_type, :status, :file, :line, :title, :test_count,
                           :failure_count, keyword_init: true)
 
+    # One exact testcase source receipt. Unlike CiResult, these are never aggregated:
+    # two tests may back the same requirement cell and each can change independently.
+    TestRevision = Struct.new(
+      :slug, :surface, :test_type, :testcase_key, :testcase_name, :classname, :outcome,
+      :repo, :file, :marker_line, :start_line, :end_line, :commit_sha,
+      :fingerprint, :fingerprint_scope,
+      keyword_init: true
+    )
+
     # A failing testcase that carries no fp:<slug> marker at all — a "loose end". Not a
     # cell on the parity grid (nothing binds it to a requirement) and not an orphan
     # marker (there is no marker); it's a red test nobody is tracking against a
@@ -58,7 +68,7 @@ module Fp
     # directory the runner was invoked from (vitest reports `src/pages/Foo.test.jsx` from
     # inside `frontend/`), so reporting it verbatim produces a link to a file that doesn't
     # exist at that path in the repo.
-    Match = Struct.new(:testcase, :marker, :precise, :repo_file, keyword_init: true)
+    Match = Struct.new(:testcase, :marker, :precise, :repo_file, :source_path, keyword_init: true)
 
     # Evidence discovered by binding a testcase to a marker.
     # `line` is the 1-based line number of the test in its source file: the
@@ -234,9 +244,13 @@ module Fp
     # A slug is `failing` if any test claiming it went red, `stub` if every test claiming
     # it was skipped (a skipped test is not proof of anything), and `passing` otherwise.
     #
-    # Returns { results: [CiResult, ...], unmatched: [TestCase], missing_surface: [...] }.
-    def ci_results(testcases, base_dir: Dir.pwd, default_surface: nil, default_test_type: nil)
+    # Returns { results: [CiResult, ...], test_revisions: [TestRevision, ...],
+    #           unmatched: [TestCase], missing_surface: [...] }.
+    def ci_results(testcases, base_dir: Dir.pwd, default_surface: nil, default_test_type: nil,
+                   commit_sha: nil, repo: nil)
       aggregates = {}
+      test_revisions = []
+      fingerprint_cache = {}
       matched = {}
       missing_surface = []
 
@@ -251,6 +265,8 @@ module Fp
         # The marker's own type pin wins; otherwise the --test-type default (nil → the
         # server files it as `unspecified`). One CI verdict per (slug, surface, type).
         test_type = marker[:test_type] || default_test_type
+        fingerprint = fingerprint_cache[[match.source_path, marker[:line]]] ||=
+          SourceFingerprint.build(match.source_path, marker)
 
         surfaces.each do |surface|
           if surface.nil? || surface.empty?
@@ -276,6 +292,18 @@ module Fp
             agg[:title] ||= title
             agg[:failing_title] ||= title if tc.failed?
           end
+
+          if fingerprint && commit_sha
+            outcome = if tc.stub? then 'stub' elsif tc.failed? then 'failing' else 'passing' end
+            test_revisions << TestRevision.new(
+              slug: marker[:slug], surface: surface, test_type: test_type,
+              testcase_key: testcase_key(match.repo_file, tc), testcase_name: tc.name,
+              classname: tc.classname, outcome: outcome, repo: repo, file: match.repo_file,
+              marker_line: marker[:line], start_line: fingerprint.start_line,
+              end_line: fingerprint.end_line, commit_sha: commit_sha,
+              fingerprint: fingerprint.fingerprint, fingerprint_scope: fingerprint.scope
+            )
+          end
         end
       end
 
@@ -293,7 +321,12 @@ module Fp
       end
 
       unmatched = testcases.reject { |tc| matched[tc.object_id] }
-      { results: results, unmatched: unmatched, missing_surface: missing_surface.uniq }
+      {
+        results: results,
+        test_revisions: test_revisions,
+        unmatched: unmatched,
+        missing_surface: missing_surface.uniq
+      }
     end
 
     # The loose ends in a set of unmatched testcases: the ones that *failed* but carry no
@@ -326,11 +359,23 @@ module Fp
           marker, precise = marker_for(tc, cases, markers)
           next unless marker
 
-          yield Match.new(testcase: tc, marker: marker, precise: precise, repo_file: repo_file)
+          yield Match.new(
+            testcase: tc, marker: marker, precise: precise, repo_file: repo_file,
+            source_path: File.expand_path(file, base_dir)
+          )
         end
       end
     end
 
+    # Stable across body edits and line movement. A rename or move is intentionally a
+    # new identity; marker syntax has no durable per-test id from which to infer that the
+    # renamed testcase is the old one.
+    def testcase_key(repo_file, testcase)
+      Digest::SHA256.hexdigest(
+        [repo_file, testcase.classname, testcase.name].map(&:to_s).join("\0")
+      )
+    end
+
     # The repository root containing `dir`, or nil when `dir` isn't inside one.    #
     # Found by walking up for a `.git` entry rather than shelling out to git, so it also
     # works in a worktree (where `.git` is a file) and costs nothing.

data/lib/fp/source_fingerprint.rb

@@ -0,0 +1,193 @@
+# frozen_string_literal: true
+
+require 'digest'
+
+module Fp
+  # Produces a receipt for the exact test source CI executed. Isolation is deliberately
+  # conservative: when a complete test body cannot be identified confidently, the whole
+  # file is hashed and the scope says so instead of pretending a noisy file hash is an
+  # isolated test receipt.
+  module SourceFingerprint
+    Result = Struct.new(:fingerprint, :scope, :start_line, :end_line, keyword_init: true)
+
+    BRACE_EXTENSIONS = %w[.js .jsx .mjs .cjs .ts .tsx .kt .kts .swift .java .go .cs .php .rs .scala].freeze
+
+    module_function
+
+    def build(path, marker)
+      contents = File.binread(path)
+      lines = contents.lines
+      range = isolated_range(lines, marker, File.extname(path).downcase)
+
+      if range
+        first, last = range
+        source = lines[first..last].join
+        Result.new(
+          fingerprint: Digest::SHA256.hexdigest(source),
+          scope: 'isolated_test',
+          start_line: first + 1,
+          end_line: last + 1
+        )
+      else
+        Result.new(
+          fingerprint: Digest::SHA256.hexdigest(contents),
+          scope: 'whole_file',
+          start_line: 1,
+          end_line: lines.length
+        )
+      end
+    rescue Errno::ENOENT, Errno::EACCES
+      nil
+    end
+
+    def isolated_range(lines, marker, extension)
+      return nil unless marker[:title_kind] == :test
+
+      start_index = declaration_index(lines, marker)
+      return nil if start_index.nil? || start_index.negative? || start_index >= lines.length
+
+      case extension
+      when '.rb'
+        ruby_range(lines, start_index)
+      when '.py'
+        python_range(lines, start_index)
+      when *BRACE_EXTENSIONS
+        brace_range(lines, start_index)
+      end
+    end
+
+    def declaration_index(lines, marker)
+      marker_index = marker[:line].to_i - 1
+      ((marker_index + 1)...[marker_index + 41, lines.length].min).each do |index|
+        line = lines[index]
+        stripped = line.strip
+        next if stripped.empty? || stripped.match?(%r{\A(?:#|//|--|/\*|\*)})
+
+        return index
+      end
+      nil
+    end
+
+    def ruby_range(lines, start_index)
+      declaration = strip_ruby_literals(lines[start_index])
+      return nil if declaration.nil?
+      return nil unless declaration.match?(/\bdef\s+test_?\w+/i) ||
+                        declaration.match?(/\b(?:it|specify|scenario)\b.*\bdo\b/)
+
+      depth = 0
+      (start_index...lines.length).each do |index|
+        code = strip_ruby_literals(lines[index])
+        return nil if code.nil?
+
+        depth += code.scan(/\bdo\b/).length
+        depth += 1 if code.match?(/^\s*(?:def|class|module|if|unless|case|begin|while|until|for)\b/)
+        depth -= code.scan(/\bend\b/).length
+        return [start_index, index] if depth.zero? && index >= start_index
+        return nil if depth.negative?
+      end
+      nil
+    end
+
+    def strip_ruby_literals(line)
+      return nil if line.match?(/<<[-~]?['"`]?\w+/)
+
+      line.gsub(/'(?:\\.|[^'\\])*'|"(?:\\.|[^"\\])*"/, '').sub(/#.*/, '')
+    end
+
+    def python_range(lines, start_index)
+      declaration = lines[start_index]
+      return nil unless declaration.match?(/^\s*(?:async\s+)?def\s+test_?\w+.*:\s*(?:#.*)?$/i)
+
+      indent = declaration[/\A\s*/].length
+      last_body = nil
+      ((start_index + 1)...lines.length).each do |index|
+        line = lines[index]
+        next if line.strip.empty? || line.lstrip.start_with?('#')
+
+        current_indent = line[/\A\s*/].length
+        break if current_indent <= indent
+
+        last_body = index
+      end
+      last_body ? [start_index, last_body] : nil
+    end
+
+    def brace_range(lines, start_index)
+      depth = 0
+      opened = false
+      in_block_comment = false
+
+      (start_index...lines.length).each do |index|
+        sanitized, in_block_comment = strip_brace_literals(lines[index], in_block_comment)
+        return nil if sanitized.nil?
+
+        sanitized.each_char do |char|
+          if char == '{'
+            depth += 1
+            opened = true
+          elsif char == '}' && opened
+            depth -= 1
+            return nil if depth.negative?
+          end
+        end
+
+        return [start_index, index] if opened && depth.zero?
+        return nil if !opened && index - start_index >= 10
+      end
+      nil
+    end
+
+    # Remove comments and quoted strings before balancing braces. Template literals are
+    # intentionally unsupported because interpolation can contain real code braces; those
+    # files use the labelled whole-file fallback rather than risk a false boundary.
+    def strip_brace_literals(line, in_block_comment)
+      return [nil, in_block_comment] if line.include?('`')
+
+      output = +''
+      quote = nil
+      escaped = false
+      index = 0
+      while index < line.length
+        char = line[index]
+        pair = line[index, 2]
+
+        if in_block_comment
+          if pair == '*/'
+            in_block_comment = false
+            index += 2
+          else
+            index += 1
+          end
+          next
+        end
+
+        if quote
+          if escaped
+            escaped = false
+          elsif char == '\\'
+            escaped = true
+          elsif char == quote
+            quote = nil
+          end
+          index += 1
+          next
+        end
+
+        break if pair == '//'
+        if pair == '/*'
+          in_block_comment = true
+          index += 2
+          next
+        end
+        if char == '"' || char == "'"
+          quote = char
+        else
+          output << char
+        end
+        index += 1
+      end
+
+      [output, in_block_comment]
+    end
+  end
+end

data/lib/fp/version.rb

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

data/lib/fp.rb

@@ -5,6 +5,7 @@ require_relative 'fp/config'
 require_relative 'fp/project_config'
 require_relative 'fp/parity'
 require_relative 'fp/client'
+require_relative 'fp/source_fingerprint'
 require_relative 'fp/junit'
 require_relative 'fp/output'
 require_relative 'fp/commands'

data/skills/fp/SKILL.md

@@ -86,6 +86,27 @@ requirement around it. Identify which promise matches product intent, then use
 `fp propose-change` (or `--removal`) with the source and reason to put that decision before a
 human. If the intent is unclear, stop and ask rather than making the catalog say both things.
 
+**Treat existing tests as protected product evidence.** Before editing an existing test,
+determine what expectation it already records and whether CI has passing evidence for it.
+
+- If the test backs passing evidence, do not rewrite it to make the current implementation or a
+  new requirement fit. Explicitly flag the intended test edit in the work item and pull request.
+  If its expected behaviour would change, propose the requirement change and wait for explicit
+  human approval before editing the test; a newly green run must not hide that the proof changed.
+- When FeatureParity reports a changed bound test, run `fp changed-tests` (or add `--json`) and
+  compare its accepted and candidate revisions with the requirement. Record a plain-language
+  assessment for the exact candidate fingerprint with `fp changed-tests assess`: `still_proves`
+  resolves only that fingerprint; `no_longer_proves` and `uncertain` remain open for a human
+  product decision. A later fingerprint always needs a new assessment.
+- A new requirement does not retroactively own or supersede a pre-existing failing test, whether
+  it is draft or active. Do not change that test, or adopt it as the new requirement's proof,
+  merely to make new work pass. Surface the conflict and wait for explicit human approval to
+  change the existing expectation.
+
+A changed-test finding is an audit signal alongside the independent CI outcome, not a failed
+test. It is also separate from `suspect`, which means requirement wording changed and its
+evidence needs re-verification. Neither permits rewriting a test before product intent is decided.
+
 ### 2. Add the fp:<slug> marker to tests
 
 Place a comment immediately before the test to bind it to a requirement:
@@ -118,6 +139,16 @@ fp report <slug> \
 
 **Agents report `present` (default) or `stub` only. Never `passing` or `failing`.**
 
+**Don't re-report a cell CI already covers.** CI evidence (`passing`, `pr_passing`,
+`failing`) is authoritative. If CI has already run the test for a surface, a `present`
+report adds nothing — it won't upgrade the cell, and the server will keep the CI verdict
+rather than downgrade it to a bare marker. Check first with `fp show <slug> --project X`
+(or `fp matrix`): if the surface already shows a CI status, skip the report. Report
+`present`/`stub` for surfaces CI hasn't reached yet — e.g. a brand-new test before its
+first CI run, or local work where CI isn't wired up. When you do report over a CI-covered
+cell anyway, `fp report` now tells you it was superseded (the status stays CI's, your
+report lands as metadata only) so you can see the no-op instead of assuming it took.
+
 ### 4. Report evidence from JUnit XML (batch upload without CI)
 
 When CI isn't available, run the suite locally and upload the report:
@@ -319,6 +350,37 @@ FeatureParity section in `AGENTS.md`):
 fp init --project <slug> --surface <surface>
 ```
 
+### Triage requirement quality (`fp analyze`)
+
+`fp analyze` checks how well requirements are written and whether they belong in the
+catalog at all. It is **read-only: it never proposes anything.** Sweep first, report, and
+only file the proposals a human picks — every proposal moves its requirement back to draft
+and marks its evidence `suspect`, and a requirement holds one open proposal at a time, so
+proposing on every flag could put dozens of requirements in review at once.
+
+```bash
+fp analyze --project stowzilla                    # sweep active + draft requirements
+fp analyze print_container_qr --project stowzilla # one requirement, with suggestions
+fp analyze --project stowzilla --conflicts        # also check for contradictions (slower)
+fp analyze --project stowzilla --cached           # read saved results only, no model calls
+fp analyze --project stowzilla --json
+```
+
+It goes one requirement at a time. Results are cached until the wording changes, so a
+re-run only pays for requirements that are new or edited. Requirements with a change
+already awaiting review are skipped.
+
+Each finding suggests a kind of follow-up. Treat it as a signal that something is wrong,
+not as the fix — you still write the proposal.
+
+| Finding | Suggested follow-up |
+|---------|---------------------|
+| Possible conflict with another requirement | Stop and ask a human — a contradiction is a product decision. Read both requirements first; the analyzer says *that* they clash, not *why* |
+| Duplicate (the report names `superseded by: <slug>`) | `fp propose-change <slug> --removal --reason "superseded by <other>"` |
+| Fragment of a broader promise (`is_focused_promise` fails) | Fold it into the parent's acceptance: `fp propose-change <parent>` for the wording, then `--removal` for the fragment |
+| Not a product promise / not observable | A human decides whether it belongs; don't guess |
+| Missing why, vague acceptance, implementation detail, boilerplate | `fp propose-change <slug> --why "..." --acceptance "..."` |
+
 ## Quick reference
 
 | Task | Command |
@@ -333,6 +395,7 @@ fp init --project <slug> --surface <surface>
 | Propose a change | `fp propose-change <slug> --project X --why "..." --reason "..."` |
 | Propose a deletion | `fp propose-change <slug> --project X --removal --reason "..."` |
 | View change history | `fp history <slug> --project X` |
+| Triage requirement quality | `fp analyze --project X` |
 | View work-item activity | `fp changes --project X --source-url URL` |
 | Enforce parity | `fp check --project X` |
 | Gate on this run | `fp check --project X --surface Y --junit file.xml` |

data/skills/fp/references/cli.md

@@ -146,6 +146,12 @@ an existing promise is a contradiction signal: decide which promise reflects pro
 then record that decision with `fp propose-change` or `--removal`. Do not weaken the test or add
 a second requirement around the conflict; ask a human when product intent is unclear.
 
+Existing tests are protected product evidence. Flag any intended edit to a test that backs
+passing evidence; if its expected behaviour would change, wait for explicit human approval of
+the requirement change before editing it. A new requirement does not supersede a pre-existing
+failing test merely because the requirement was drafted or activated. Surface that conflict and
+do not change or adopt the old test as proof without explicit human approval.
+
 ```bash
 fp propose --project stowzilla \
   --slug current_shipment_status \
@@ -270,6 +276,37 @@ the review decision where one was made. An open proposal is called out at the en
 
 `--project` is optional when the repo has a `.featureparity.yml`.
 
+### fp analyze
+
+Triage requirement quality: duplicates, fragments of a broader promise, vague wording,
+possible conflicts. **Read-only — it never files a proposal.** Report first; a human
+picks which proposals to file (each moves its requirement to draft).
+
+```bash
+fp analyze --project stowzilla                     # active + draft requirements
+fp analyze print_container_qr --project stowzilla  # one requirement, with suggestions
+fp analyze --project stowzilla --status active     # narrow the sweep
+fp analyze --project stowzilla --conflicts         # also check contradictions (slower)
+fp analyze --project stowzilla --force             # re-run even if the result is current
+fp analyze --project stowzilla --cached            # saved results only, no model calls
+fp analyze --project stowzilla --json
+```
+
+Analysis costs one model call per requirement, so the sweep runs one request at a time
+rather than asking the server to do the whole catalog at once (which cannot finish inside
+the API timeout). Results are cached until a requirement's title, why, or acceptance
+changes, so re-running only pays for new or edited requirements. A requirement with a
+change awaiting review is skipped.
+
+The report groups findings by suggested follow-up: **conflict** (ask a human),
+**propose removal** (duplicate — with `superseded by: <slug>` — or a fragment of a broader
+promise), **needs human** (not clearly a product promise), **propose change** (wording
+issues), plus in-review, not-analyzed (`--cached` only), and error. `--conflicts` adds
+the other requirement's slug, a probability, and both acceptance clauses side by side —
+the analyzer flags the clash but cannot explain it.
+
+`--project` is optional when the repo has a `.featureparity.yml`.
+
 ### fp changes
 
 Show requirement activity prompted by a work item, rather than opening every requirement's
@@ -295,6 +332,60 @@ item says FeatureParity cannot determine the activity; a linked work item with n
 explicitly says no requirement changes were recorded. Generated `fp init` workflows configure
 both outputs before the parity gate.
 
+### fp changed-tests
+
+List every unresolved audit finding for a bound test whose source fingerprint differs from
+the accepted revision. The queue is independent of the testcase's passing/failing/stub outcome
+and from `suspect` evidence caused by changed requirement wording.
+
+```bash
+fp changed-tests                                      # project from .featureparity.yml
+fp changed-tests --project stowzilla --surface api
+fp changed-tests --json                               # complete machine-readable queue
+```
+
+Each finding includes the current requirement and acceptance rule, surface and optional test
+type, testcase and CI outcome, isolated-test or labelled whole-file fingerprint scope, and the
+accepted and candidate fingerprints, commits, source locations, and links.
+
+After comparing those exact revisions with the requirement, an authorized agent records a
+plain-language assessment:
+
+```bash
+fp changed-tests assess <finding-id> \
+  --candidate-fingerprint <sha256> \
+  --classification still_proves \
+  --explanation "The refactor changes setup only; the same observable result is asserted."
+```
+
+Classifications are `still_proves`, `no_longer_proves`, and `uncertain`. `still_proves`
+resolves only the supplied candidate fingerprint; if it came from a PR, that exact fingerprint
+becomes the accepted baseline only after a default-branch CI report observes it. The other two
+classifications remain open for a human product decision. A stale candidate is rejected, and a
+later fingerprint always requires a new assessment. Assessing never changes the requirement
+wording or CI outcome.
+
+#### Upgrading an existing project
+
+Changed-test auditing requires fp 0.0.17 or newer and the corresponding backend deployment.
+Hosted-project users do not migrate project data or configuration.
+
+```bash
+gem update featureparity
+fp version                 # 0.0.17 or newer
+```
+
+Fresh CI jobs that run `gem install featureparity` automatically pick up the release; update
+any Bundler or install-command pin explicitly. Keep the existing `fp ci-report` call and run it
+once on the default branch: the upgraded CLI sends source receipts automatically, and that run
+lazily establishes accepted baselines without a backfill. Report trusted pull requests with
+`--pr <url>` to open findings before merge while preserving the default-branch baseline.
+
+The workflow recipe generated by fp 0.0.17 shows both paths. Adapt an existing customized
+workflow manually. `fp init --force` overwrites `.featureparity.yml` and the generated workflow,
+so reserve it for unmodified generated files, preserve the original project/surface options,
+and review the resulting diff.
+
 ### fp matrix
 
 Display the parity matrix. Cells show the state of the evidence filed for each
@@ -398,7 +489,7 @@ fp init --project stowzilla --dir path/to/repo
 | File | Purpose |
 |------|---------|
 | `.featureparity.yml` | declares the project slug, so `--project` becomes optional |
-| `.github/workflows/feature-parity.yml` | the CI gate and PR requirement-change summary |
+| `.github/workflows/feature-parity.yml` | the CI gate, PR requirement-change summary, and adaptable PR/default-branch reporting recipe |
 | `AGENTS.md` (appended) | instructions telling agents to mark and report their tests |
 
 Existing files are skipped unless `--force`. The `AGENTS.md` section is appended between