featureparity 0.0.16 → 0.0.18

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,7 +22,9 @@ 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
+            analyze [<slug>] --project <slug> Triage requirement quality (read-only; never proposes)
             changes [--source-url URL] [--github-pr]  Show or publish work-item-linked activity
             attach <slug> <file>              Upload a file attachment to a requirement
             attachments <slug>                List attachments for a requirement
@@ -33,6 +35,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 +81,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 +197,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.
@@ -234,11 +268,38 @@ module Fp
             fp history print_container_qr --project stowzilla
             fp history print_container_qr --project stowzilla --pending
 
-            # Upload a file attachment to a requirement (screenshot evidence, docs, etc.)
-            # Supported formats: png, jpg, gif, webp, svg, pdf, txt, md (max 10 MB)
-            fp attach print_container_qr screenshot.png --project stowzilla
+            # Triage the catalog's quality: duplicates, fragments, vague wording, conflicts.
+            # One model call per uncached requirement; unchanged ones are read back free.
+            fp analyze --project stowzilla
+            fp analyze print_container_qr --project stowzilla --conflicts
+
+            # Upload visual test evidence to a requirement. Images and videos require
+            # --surface; deployment fields let reviewers verify exactly what build the
+            # capture observed. --example-title names the individual test the media
+            # proves, so it shows next to that test's receipt instead of a surface-wide
+            # gallery. --evidence-key is a stronger join: it directly names the receipt
+            # by its composite key (surface:repo:test_type) so the match survives title
+            # renames.
+            #
+            # Visual formats: png, jpg, gif, webp, mp4, webm, mov
+            # Text formats: txt, md, json (render inline as code blocks for API evidence)
+            # Documents: svg, pdf (downloadable)
+            # Max 100 MB.
+            fp attach print_container_qr e2e-run.webm --project stowzilla \\
+              --surface customer_web \\
+              --example-title "prints a QR code onto the container label" \\
+              --captured-at 2026-10-15T01:42:00Z \\
+              --deployed-at 2026-10-15T01:30:00Z \\
+              --sha abc1234 \\
+              --deployment-url https://preview.example.test \\
+              --test-run-url https://github.com/stowzilla/app/actions/runs/123
+
+            # For API tests, attach the JSON response as inline evidence
+            fp attach api_returns_order_details response.json --project stowzilla \\
+              --surface api \\
+              --evidence-key "api:stowzilla/api:e2e"
 
-            # List attachments for a requirement
+            # List attachments and their capture/deployment context
             fp attachments print_container_qr --project stowzilla
 
             # Get a download URL for a specific attachment

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(', ')}")