featureparity 0.0.16 → 0.0.17

data/lib/fp/commands/init.rb

@@ -180,17 +180,19 @@ module Fp
         end
       end
 
-      # The CI gate. Two jobs on purpose: reporting evidence and enforcing the gate are
-      # separate concerns, and the gate must run on pull requests (where it blocks a
-      # merge) while evidence reporting only makes sense on trusted pushes.
+      # The CI gate and its adaptable reporting recipe are separate concerns: the gate
+      # blocks pull requests, while reporting needs a trusted context with FP_API_KEY and
+      # should cover both pull requests and default-branch pushes.
       def workflow_body
         <<~YAML
           # FeatureParity — parity enforcement.
           #
-          # Generated by `fp init`. Two jobs, deliberately separate:
+          # Generated by `fp init`. The gate is ready to use; adapt and uncomment the
+          # report recipe once this repository emits JUnit:
           #
-          #   report  On pushes to the default branch, feed test results back to
-          #           FeatureParity so the parity matrix reflects real pass/fail.
+          #   report  On trusted pull requests, report candidate test revisions before
+          #           merge. On default-branch pushes, record merged pass/fail and promote
+          #           an approved exact test revision into the accepted baseline.
           #   gate    On pull requests, fail the build when the project violates its
           #           enforcement level. Make this a required status check in branch
           #           protection to actually block merges.
@@ -261,30 +263,44 @@ module Fp
                   run: fp check
 
             # Uncomment and adapt once your suite emits JUnit XML. `fp ci-report` writes
-            # real passing/failing evidence — without it, the matrix only ever shows the
-            # `present` markers agents filed, and the gate has nothing green to see.
+            # real passing/failing evidence and one source fingerprint per bound testcase.
+            # Run it on trusted pull requests too: `--pr` lets FeatureParity open a changed-test
+            # finding before merge without replacing the accepted default-branch baseline.
+            # The later default-branch report records merged truth and promotes an approved exact
+            # fingerprint. Without reporting, the matrix only has agent-filed `present` markers
+            # and changed bound tests cannot be detected.
             #
             # It reads the fp:<slug> markers out of the checkout, so run it in the repo
             # and pass --base-dir when the report's test-file paths are relative to a
             # subdirectory (vitest, for instance, reports them relative to its package).
+            # Keep `if: always()` so red tests are reported. Fork pull requests cannot read
+            # FP_API_KEY and are skipped by the HAVE_FP_KEY guard.
             #
             # report:
             #   name: Report evidence
-            #   if: github.event_name == 'push'
+            #   if: github.event_name == 'push' || github.event_name == 'pull_request'
             #   runs-on: ubuntu-latest
+            #   env:
+            #     HAVE_FP_KEY: ${{ secrets.FP_API_KEY != '' }}
             #   steps:
             #     - uses: actions/checkout@v4
             #     - name: Run tests (emit JUnit)
             #       run: echo "replace with your test command emitting junit.xml"
             #     - name: Report to FeatureParity
-            #       if: always()
+            #       if: always() && env.HAVE_FP_KEY == 'true'
             #       env:
             #         FP_API_KEY: ${{ secrets.FP_API_KEY }}
             #       run: |
             #         gem install featureparity
-            #         fp ci-report --junit junit.xml \\
-            #           --surface <surface-key> \\
+            #         args=(
+            #           --junit junit.xml
+            #           --surface <surface-key>
             #           --ci-url "${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}"
+            #         )
+            #         if [ "${{ github.event_name }}" = "pull_request" ]; then
+            #           args+=(--pr "${{ github.event.pull_request.html_url }}")
+            #         fi
+            #         fp ci-report "${args[@]}"
         YAML
       end
 
@@ -361,6 +377,30 @@ module Fp
           `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 itself changed.
+          - When FeatureParity reports a changed bound test, run `fp changed-tests` (or add `--json`)
+            and compare the accepted and candidate source revisions with the requirement. Record the
+            exact candidate through `fp changed-tests assess <id> --candidate-fingerprint <sha256>`
+            with a plain-language explanation and one classification: `still_proves`,
+            `no_longer_proves`, or `uncertain`. The first resolves only that fingerprint; the others
+            remain open for a human product decision. A later fingerprint needs a new assessment.
+          - A new requirement does not retroactively own or supersede a pre-existing failing test —
+            whether the requirement is draft or active. Do not change that test, or adopt it as the new
+            requirement's proof, merely to make the 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 testcase's independent CI outcome.
+          It is not a failed test and is separate from `suspect`, which means requirement wording
+          changed and its evidence needs re-verification. Neither permits rewriting a test before
+          product intent is decided.
+
           If no requirement covers what you're building, propose one or a parent/child tree. Agents
           always create **drafts**; a human activates them:
 

data/lib/fp/commands/propose_change.rb

@@ -55,7 +55,11 @@ module Fp
 
         result = client.propose_requirement_change(requirement['id'], params)
         unless result[:ok]
-          output.error(result[:error], status: result[:status])
+          if result[:status] == 409 && result[:details].is_a?(Hash)
+            print_conflict(result, slug: slug)
+          else
+            output.error(result[:error], status: result[:status])
+          end
           exit 1
         end
 
@@ -64,6 +68,47 @@ module Fp
 
       private
 
+      # A 409 means the requirement already has an open proposal — the one-at-a-time rule
+      # (two "what it was" snapshots would make a rollback ambiguous). Rather than a dead
+      # end, show what the open proposal is and point at `fp comment` so the agent can
+      # raise its concern on the proposal a human is about to review.
+      def print_conflict(result, slug:)
+        pending = result[:details]['pending_change'] || {}
+
+        if output.json?
+          output.error(result[:error], status: result[:status])
+          return
+        end
+
+        warn "Error: #{result[:error]}"
+        warn ''
+        warn 'The open proposal:'
+        warn "  Change:   #{pending['id']}"
+        warn "  Kind:     #{pending['kind']}"
+        warn "  Proposed: #{pending['actor']} (#{pending['actor_kind']})"
+        warn "  Reason:   #{pending['reason']}" if pending['reason']
+        print_conflict_source(pending['source'])
+        print_conflict_diff(pending['changes'])
+        warn ''
+        warn 'You cannot open a rival proposal, but you can comment on this one:'
+        warn "  fp comment #{slug} --change #{pending['id']} --body \"...\" --project <project>"
+        warn 'Or wait for a human to review it. Run `fp history ' \
+             "#{slug} --project <project>` for the full diff."
+      end
+
+      def print_conflict_source(source)
+        return unless source.is_a?(Hash) && !source.empty?
+
+        warn "  Source:   #{source['type']}" if source['type']
+        warn "  URL:      #{source['url']}" if source['url']
+      end
+
+      def print_conflict_diff(changes)
+        return unless changes.is_a?(Hash) && !changes.empty?
+
+        warn '  Fields:   ' + changes.keys.join(', ')
+      end
+
       def validate_enums!(opts)
         if opts[:category] && !VALID_CATEGORIES.include?(opts[:category])
           output.error("Invalid category '#{opts[:category]}'. Must be one of: #{VALID_CATEGORIES.join(', ')}")

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.rb

@@ -7,10 +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.16'
+  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

@@ -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: