featureparity 0.0.15 → 0.0.17

data/lib/fp/commands/report.rb

@@ -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/show.rb

@@ -24,6 +24,7 @@ module Fp
         end
 
         requirement = result[:data]['requirement']
+        source_history = result[:data]['source_history'] || []
 
         # Evidence is not embedded in the requirement payload — it lives on the project's
         # evidence collection, keyed by slug. Fetch it, or `fp show` reports "(none)" for
@@ -37,7 +38,7 @@ module Fp
         payload['parent_slug'] = parent_slug if parent_slug
 
         output.success(payload) do
-          print_requirement(requirement, evidence: evidence, parent_slug: parent_slug)
+          print_requirement(requirement, evidence: evidence, parent_slug: parent_slug, source_history: source_history)
         end
       end
 
@@ -60,7 +61,7 @@ module Fp
         parent && parent['slug']
       end
 
-      def print_requirement(req, evidence: [], parent_slug: nil)
+      def print_requirement(req, evidence: [], parent_slug: nil, source_history: [])
         puts "#{req['title']}"
         puts "=" * req['title'].length
         puts
@@ -106,6 +107,23 @@ module Fp
           puts
         end
 
+        # Source trail: every source (Fizzy card, Discord thread, issue) that prompted a
+        # change to this requirement, oldest first. Derived from events so the history is
+        # additive — older sources aren't lost when a new one is recorded.
+        puts 'Source Trail:'
+        if source_history.empty?
+          puts '  (no sources recorded)'
+        else
+          source_history.each do |src|
+            line = []
+            line << src['type'] if src['type']
+            line << src['url'] if src['url']
+            puts "  - #{line.join(' ')}"
+            puts "    #{src['context']}" if src['context']
+          end
+        end
+        puts
+
         # Evidence receipts, newest first, grouped per surface.
         puts 'Evidence:'
         if evidence.empty?

data/lib/fp/commands.rb

@@ -7,9 +7,12 @@ 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/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.15'
+  VERSION = '0.0.17'
 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

@@ -49,6 +49,7 @@ fp list --project stowzilla --status draft     # Proposed work; avoid duplicates
 fp list --project stowzilla --gaps             # Requirements with a required surface lacking evidence
 fp show <slug> --project stowzilla             # Requirement details and evidence
 fp history <slug> --project stowzilla          # Origins and pending changes
+fp changes --source-url <work-item-url>         # Activity prompted by one card, issue, or thread
 fp matrix --project stowzilla                  # ASCII parity matrix
 fp matrix --project stowzilla --csv            # Export as CSV
 fp check --project stowzilla                   # Enforce parity (exits 1 on violations)
@@ -85,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:
@@ -117,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:
@@ -332,6 +364,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` |
+| 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` |
 | View matrix | `fp matrix --project X` |

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,85 @@ 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 changes
+
+Show requirement activity prompted by a work item, rather than opening every requirement's
+history separately.
+
+```bash
+fp changes --source-url https://app.fizzy.do/6098707/cards/1434
+fp changes --project stowzilla --source-url https://github.com/acme/app/issues/42
+fp changes --github-pr --github-summary
+```
+
+`--source-url` may be repeated. The API matches the URL exactly against the source recorded
+when a requirement was created, directly edited, proposed for modification, or proposed for
+removal. Results include the requirement, activity kind, review state, actor, and a link to the
+requirement.
+
+In a GitHub pull-request workflow, `--github-pr` reads the live PR through the GitHub API and
+writes or replaces one marker-managed requirement table in its description. It requires
+`GITHUB_TOKEN`, `GITHUB_REPOSITORY`, `GITHUB_EVENT_PATH`, and `pull-requests: write`; inability
+to read or update the PR is an error, so a missing table cannot silently pass. Add
+`--github-summary` to keep the same table in `GITHUB_STEP_SUMMARY`. A PR with no linked work
+item says FeatureParity cannot determine the activity; a linked work item with no events
+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
@@ -373,7 +458,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 |
+| `.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