featureparity 0.0.5 → 0.0.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1208887c7ed99691e476438cdcb50d36f09e3ee3b22931c7d8d9ea246438fb89
-  data.tar.gz: b2fb9b9d7bad99bde7e2f8b0789105072cd19647ed46f0ea4d4d6e43a28fd319
+  metadata.gz: d668266132dc93de82fc60d7603f340ab05a8e5852fa4cde36ce9e6e4586ff18
+  data.tar.gz: 7d1b2691eeade5eabf110c518dca40808ce1beee2a0809b422376eaf914692c4
 SHA512:
-  metadata.gz: 5d70c2ae5afb585a1f54da0c2efb244965a0f419001c9ed8f46d1895a5f37ee12ece8a1195627859eeeaff2fd3910cf4dfdb593fc41c69440bc97020ff31a17a
-  data.tar.gz: 23d9038f6850138f295501a56ea00f872ff828eab5a2822482c306a56ba39cdec2a1016761af8f4f87932a3d9f264faf0c9dad3302d2a96ea5adceb86b3e29c6
+  metadata.gz: dafb288e14865ffd01b3cf739a510b8c7c2cf103b5e0867b07ce8f79264a14e8ab34ef95a01a73a77c3566adc2ce792488a3581f8ca184f1cd9b0678f8a4bce2
+  data.tar.gz: eee75e4d691fbd6884b0d417a1e8a9ae8c88e15da95ad1919b64f9a7e6a1ed915a5a8baa2687603cbe9d41a3f27738d4b0ae360d3ec97efb0885c45e62b4bcaf

data/lib/fp/cli.rb

@@ -4,13 +4,19 @@ module Fp
   # Main CLI entry point - parses global flags and dispatches to commands
   class CLI
     COMMANDS = {
+      'init' => Commands::Init,
       'projects' => Commands::Projects,
       'surfaces' => Commands::Surfaces,
       'list' => Commands::List,
       'show' => Commands::Show,
       'propose' => Commands::Propose,
+      'propose-change' => Commands::ProposeChange,
+      'history' => Commands::History,
       'report' => Commands::Report,
+      'ci-report' => Commands::CiReport,
+      'check' => Commands::Check,
       'matrix' => Commands::Matrix,
+      'export' => Commands::Export,
       'profile' => Commands::Profile,
       'config' => Commands::ConfigCmd,
       'repos' => Commands::Repos,
@@ -35,8 +41,9 @@ module Fp
           exit 1
         end
 
-        # Profile/config commands don't need auth
-        needs_auth = !%w[profile config repos setup whoami version help].include?(command_name)
+        # Profile/config commands don't need auth. `init` is here too: it only writes
+        # files into the repo, and onboarding a repo must work before anyone has a key.
+        needs_auth = !%w[init profile config repos setup whoami version help].include?(command_name)
 
         if needs_auth
           config = Config.new(profile: global_opts[:profile], api_url: global_opts[:api_url])

data/lib/fp/client.rb

@@ -72,6 +72,30 @@ module Fp
       put("/api/requirements/#{id}", params)
     end
 
+    # GET /requirements/:id/changes
+    #
+    # A requirement's change history: what it was, what changed, who changed it, and
+    # what prompted the change. Includes the open proposal (if any) broken out.
+    def list_requirement_changes(requirement_id)
+      get("/api/requirements/#{requirement_id}/changes")
+    end
+
+    # POST /requirements/:id/changes
+    #
+    # Propose a modification, or a deletion when params[:removal] is true. The
+    # requirement drops back to draft until a human reviews it.
+    def propose_requirement_change(requirement_id, params)
+      post("/api/requirements/#{requirement_id}/changes", params)
+    end
+
+    # PUT /requirements/:id/changes/:change_id
+    #
+    # Approve or reject an open proposal. Humans only — an agent key gets a 403, which
+    # is deliberate and printed verbatim.
+    def review_requirement_change(requirement_id, change_id, params)
+      put("/api/requirements/#{requirement_id}/changes/#{change_id}", params)
+    end
+
     # GET /projects/:project_id/evidence — the receipts already filed for a project,
     # optionally narrowed to one requirement slug and/or surface.
     def list_evidence(project_id, slug: nil, surface: nil)
@@ -87,17 +111,49 @@ module Fp
       post("/api/projects/#{project_id}/evidence", params)
     end
 
-    # GET /matrix (when API is ready)
-    def get_matrix(project_id, format: :json)
-      path = format == :csv ? '/api/matrix.csv' : '/api/matrix'
-      get(path, { project_id: project_id })
-    end
-
-    # GET /gaps (when API is ready)
-    def get_gaps(project_id, surface: nil)
-      params = { project_id: project_id }
+    # POST /projects/:project_id/ci_results — the CI-only path.
+    #
+    # Unlike report_evidence (agents: present/stub), this hands the raw JUnit XML
+    # to the backend, which parses it, maps testcases to fp:<slug> markers, and
+    # writes passing/failing evidence per surface. It also marks previously
+    # passing slugs that have vanished from the results as failing. This is the
+    # half of the loop only CI is allowed to close (#1222).
+    def ingest_ci_results(project_id, ci_url:, surface:, junit_xml:)
+      post("/api/projects/#{project_id}/ci_results", {
+             ci_url: ci_url,
+             surface: surface,
+             junit_xml: junit_xml
+           })
+    end
+
+    # GET /projects/:project_id/parity — the computed parity grid and gate verdict.
+    #
+    # This replaces the old get_matrix/get_gaps stubs, which pointed at /api/matrix
+    # and /api/gaps — routes that were never built. `fp matrix` and `fp list --gaps`
+    # never called them, and instead each guessed at coverage client-side from
+    # required_surfaces without ever reading Evidence. The server now does the
+    # cross-referencing so the matrix, the gaps list, and the CI gate agree.
+    #
+    # @param level [String, nil] enforcement level override; nil uses the project's own
+    # @param surface [String, nil] restrict the report to a single surface key
+    def get_parity(project_id, level: nil, surface: nil)
+      params = {}
+      params[:level] = level if level
       params[:surface] = surface if surface
-      get('/api/gaps', params)
+      get("/api/projects/#{project_id}/parity", params)
+    end
+
+    # POST /projects/:project_id/parity/preview — the pull-request gate.
+    #
+    # Evaluates JUnit results as an overlay on the stored grid *without persisting them*,
+    # answering "would parity still hold if this merged?". GET parity can only describe
+    # what has already been recorded, which on a PR is the default branch's state; this
+    # is how a branch gets gated on its own results without writing evidence that would
+    # churn the live matrix.
+    def preview_parity(project_id, surface:, junit_xmls:, level: nil)
+      body = { surface: surface, junit_xmls: Array(junit_xmls) }
+      body[:level] = level if level
+      post("/api/projects/#{project_id}/parity/preview", body)
     end
 
     private

data/lib/fp/commands/base.rb

@@ -80,11 +80,60 @@ module Fp
         end
       end
 
+      # Resolve which project a command should act on, filling in opts[:project] from the
+      # repo-local .featureparity.yml when --project wasn't given.
+      #
+      # That fallback is what makes enforcement workable in CI and for agents: a
+      # generated workflow, and an agent in a fresh clone, shouldn't have to know (or
+      # duplicate) the project slug when the repo already declares it.
+      #
+      # Mutates opts rather than returning a separate value so the existing
+      # resolve_project_id / display code in each command needs no changes.
+      # Returns the slug; exits 1 with guidance when neither source has one.
+      def require_project!(opts, project_config = nil)
+        opts[:project] ||= (project_config || ProjectConfig.discover).project
+
+        unless opts[:project]
+          output.error(
+            '--project is required (or add `project: <slug>` to .featureparity.yml — see `fp init`)'
+          )
+          exit 1
+        end
+
+        opts[:project]
+      end
+
       def truncate(str, max)
         return str if str.nil? || str.length <= max
 
         str[0...max - 3] + '...'
       end
+
+      # Pull every occurrence of a repeatable flag out of args, returning
+      # [values, remaining_args].
+      #
+      # parse_flags keeps only the last occurrence of a repeated flag, so a flag that may
+      # legitimately appear more than once (--junit, for a suite split across shards) has
+      # to be extracted before the normal parse. Shared by `fp ci-report` and `fp check`.
+      def extract_repeated(args, flag)
+        values = []
+        rest = []
+        i = 0
+        while i < args.length
+          arg = args[i]
+          if arg == flag && i + 1 < args.length
+            values << args[i + 1]
+            i += 2
+          elsif arg.start_with?("#{flag}=")
+            values << arg.split('=', 2)[1]
+            i += 1
+          else
+            rest << arg
+            i += 1
+          end
+        end
+        [values, rest]
+      end
     end
   end
 end

data/lib/fp/commands/check.rb

@@ -0,0 +1,216 @@
+# frozen_string_literal: true
+
+module Fp
+  module Commands
+    # fp check [--project X] [--surface api] [--level covered] [--junit FILE] [--json]
+    #
+    # The enforcement gate. Fetches the parity report and exits non-zero when the
+    # project violates its enforcement level, which is what makes it usable as a
+    # required status check on a pull request.
+    #
+    # Two modes:
+    #
+    #   fp check                      Gate on what has been recorded. Answers "is this
+    #                                 project currently in violation?"
+    #   fp check --junit r.xml        Gate on *this run's* results, applied on top of the
+    #     --surface api               recorded grid but never saved. Answers "would parity
+    #                                 still hold if this branch merged?"
+    #
+    # The second is the pull-request gate. Without it a PR run can only see the default
+    # branch's state, so it can't tell you that the branch in front of it deleted the only
+    # test covering a requirement. Reporting the branch's evidence for real would answer
+    # that too, but would let every in-progress branch churn the live matrix — so the
+    # results are evaluated and thrown away.
+    #
+    # Everything about *what counts as a violation* lives server-side in ParityReport —
+    # this command renders the verdict and turns it into an exit code. That split is
+    # deliberate: if the policy lived in the CLI, every repo would enforce whichever
+    # version of the gem its CI happened to install.
+    #
+    # Exit codes are the contract CI reads:
+    #   0  gate passed
+    #   1  gate failed (violations), or the request failed
+    #
+    # `--warn-only` reports violations and still exits 0, for landing the gate on a repo
+    # that isn't clean yet — you get the annotations without blocking every merge on day
+    # one. Prefer setting the project's level to `regression` over living on --warn-only
+    # forever, since a warn-only gate is one nobody reads.
+    class Check < Base
+      KNOWN_FLAGS = {
+        project: :string,
+        surface: :string,
+        level: :string,
+        junit: :string,
+        warn_only: :boolean
+      }.freeze
+
+      def run(args)
+        # Collect every --junit occurrence (parse_flags keeps only the last of a repeated
+        # flag), matching `fp ci-report`.
+        junit_paths, rest = extract_repeated(args, '--junit')
+        opts, = parse_flags(rest, KNOWN_FLAGS)
+
+        project_config = ProjectConfig.discover
+        project_slug = require_project!(opts, project_config)
+
+        surface = opts[:surface] || project_config.surface
+        level = opts[:level] || project_config.enforcement
+
+        project_id = resolve_project_id(project_slug)
+
+        result =
+          if junit_paths.empty?
+            client.get_parity(project_id, level: level, surface: surface)
+          else
+            preview(project_id, junit_paths, surface, level)
+          end
+
+        unless result[:ok]
+          output.error(result[:error], status: result[:status])
+          exit 1
+        end
+
+        report = result[:data]['parity'] || {}
+        violations = report['violations'] || []
+        passed = report['passing']
+
+        render(report, violations, passed, project_slug, opts)
+
+        # A failing gate is the whole point of the command, so it must be the exit code
+        # and not just something printed. --warn-only downgrades it to advisory.
+        exit 1 if !passed && !opts[:warn_only]
+      end
+
+      private
+
+      # Preview mode needs to know which surface the results belong to, because the
+      # server uses it to decide which cells the run had a chance to cover — and
+      # therefore which vanished tests it may legitimately flag.
+      def preview(project_id, junit_paths, surface, level)
+        unless surface
+          output.error(
+            '--surface is required with --junit (the surface these results are for). ' \
+            'Set it via --surface or `surface:` in .featureparity.yml.'
+          )
+          exit 1
+        end
+
+        missing = junit_paths.reject { |p| File.file?(p) }
+        unless missing.empty?
+          output.error("JUnit file(s) not found: #{missing.join(', ')}")
+          exit 1
+        end
+
+        client.preview_parity(
+          project_id,
+          surface: surface,
+          junit_xmls: junit_paths.map { |p| File.read(p) },
+          level: level
+        )
+      end
+
+      def render(report, violations, passed, project_slug, opts)
+        payload = report.merge('project' => project_slug, 'warn_only' => !!opts[:warn_only])
+
+        output.success(payload) do
+          summary = report['summary'] || {}
+          scope = report['surface'] ? " (surface: #{report['surface']})" : ''
+          puts "FeatureParity gate: #{project_slug}#{scope}"
+          puts "Enforcement level: #{report['level']}"
+          if report['preview']
+            reported = Array(report['preview_surfaces']).join(', ')
+            puts "Mode: preview — evaluating this run's results#{reported.empty? ? '' : " for #{reported}"} (nothing saved)"
+          end
+          puts
+
+          if (report['surfaces'] || []).empty?
+            puts 'This project has no surfaces configured, so there is nothing to enforce.'
+            puts "Add one with: fp surfaces add <key> --project #{project_slug}"
+            next
+          end
+
+          if summary['requirements'].to_i.zero?
+            puts 'No requirements to measure. Nothing to enforce yet.'
+            next
+          end
+
+          print_state_counts(summary)
+          print_violations(violations)
+          print_pending_reviews(report, project_slug)
+          print_unscoped_warning(summary, project_slug)
+          print_verdict(passed, violations, opts)
+        end
+      end
+
+      def print_state_counts(summary)
+        counts = Parity.count_labels(summary)
+
+        puts "#{summary['requirements']} requirement(s) measured, #{summary['cells']} required surface(s)"
+        puts "  #{counts.join('   ')}" unless counts.empty?
+        puts
+      end
+
+      # Requirements a proposed change has knocked back to draft. Informational, never a
+      # violation — a human's review latency is not something to fail an agent's build
+      # over. But they stay in the grid (proposing a change must not be a way out of the
+      # gate), and proposing marks their evidence `suspect`, so saying nothing here would
+      # leave a reader guessing why a row that was green went ⚠.
+      def print_pending_reviews(report, project_slug)
+        pending = report['pending_reviews'] || []
+        return if pending.empty?
+
+        puts "#{pending.size} requirement(s) awaiting review of a proposed change " \
+             "(#{Parity.pending_summary(pending)}):"
+        output.table(
+          %w[SLUG PROPOSED TITLE],
+          pending.map { |p| [p['slug'], p['kind'], truncate(p['title'].to_s, 48)] }
+        )
+        puts 'These still count toward the gate — proposing a change is not a way out of it.'
+        puts "Their evidence is suspect until the change is reviewed:  fp history <slug>#{project_scope(project_slug)}"
+        puts
+      end
+
+      def print_violations(violations)
+        return if violations.empty?
+
+        puts "#{violations.size} violation(s):"
+        output.table(
+          %w[SLUG SURFACE STATE WHY],
+          violations.map do |v|
+            [v['slug'], v['surface'], "#{Parity.glyph(v['state'])} #{v['state']}", v['reason']]
+          end
+        )
+        puts
+      end
+
+      # Informational, never a violation: an active requirement naming no surface this
+      # project has can't be satisfied, so it would pass any gate silently. Worth
+      # saying out loud without blocking a merge on someone else's data-entry gap.
+      # `--project` is only worth echoing in a suggested command when the slug didn't
+      # come from .featureparity.yml — otherwise it's noise the agent would copy.
+      def project_scope(project_slug)
+        ProjectConfig.discover.project ? '' : " --project #{project_slug}"
+      end
+
+      def print_unscoped_warning(summary, project_slug)
+        unscoped = summary['unscoped'].to_i
+        return unless unscoped.positive?
+
+        puts "Note: #{unscoped} requirement(s) name no surface this project has, so " \
+             'nothing can satisfy them.'
+        puts "      Review with: fp list --project #{project_slug}"
+        puts
+      end
+
+      def print_verdict(passed, violations, opts)
+        if passed
+          puts 'Gate passed.'
+        elsif opts[:warn_only]
+          puts "Gate FAILED with #{violations.size} violation(s) — exiting 0 because --warn-only was given."
+        else
+          puts "Gate FAILED with #{violations.size} violation(s)."
+        end
+      end
+    end
+  end
+end

data/lib/fp/commands/ci_report.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+module Fp
+  module Commands
+    # CI-only evidence reporting from a JUnit XML report.
+    #
+    #   fp ci-report --junit <path> --project <slug> --surface X --ci-url URL
+    #
+    # This is the CI counterpart to `fp report --junit`. Where `fp report`
+    # writes agent evidence (present/stub) and never claims a test passed, this
+    # command hands the raw JUnit XML to the backend's CI ingest endpoint, which:
+    #
+    #   - maps each testcase to its fp:<slug> marker (server-side, same
+    #     file-scanning convention as the CLI),
+    #   - writes passing / failing evidence per requirement for the surface,
+    #   - and marks any slug that was passing but has now vanished from the
+    #     report as failing.
+    #
+    # That last part is why the whole report goes up as one document rather than
+    # per-slug: the server can only detect a disappeared test by diffing the full
+    # result set against what it had. Reporting passing/failing is a privilege of
+    # CI (#1222) — agents can't reach this path, they only ever report evidence
+    # via `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.
+    class CiReport < Base
+      KNOWN_FLAGS = {
+        project: :string,
+        surface: :string,
+        ci_url: :string,
+        junit: :string
+      }.freeze
+
+      def run(args)
+        # Collect every --junit occurrence (parse_flags keeps only the last of a
+        # repeated flag, so pull them out first).
+        junit_paths, rest = extract_repeated(args, '--junit')
+        opts, _positional = parse_flags(rest, KNOWN_FLAGS)
+
+        require_project!(opts)
+        require_flag(opts, :surface)
+        require_flag(opts, :ci_url)
+
+        if junit_paths.empty?
+          output.error('--junit <path> is required (may be given more than once).')
+          exit 1
+        end
+
+        missing = junit_paths.reject { |p| File.file?(p) }
+        unless missing.empty?
+          output.error("JUnit file(s) not found: #{missing.join(', ')}")
+          exit 1
+        end
+
+        project_id = resolve_project_id(opts[:project])
+
+        totals = { created: 0, updated: 0, missing_failing: 0, reports: [] }
+
+        junit_paths.each do |path|
+          xml = File.read(path)
+          result = client.ingest_ci_results(
+            project_id,
+            ci_url: opts[:ci_url],
+            surface: opts[:surface],
+            junit_xml: xml
+          )
+
+          unless result[:ok]
+            output.error("Failed to ingest #{path}: #{result[:error]}", status: result[:status])
+            exit 1
+          end
+
+          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'] || [] }
+        end
+
+        emit_summary(opts, totals)
+      end
+
+      private
+
+      # Pull every occurrence of a repeatable flag (and its value) out of args,
+      # returning [collected_values, remaining_args]. Leaves all other flags for
+      # the normal parser.
+      def emit_summary(opts, totals)
+        data = {
+          project: opts[:project],
+          surface: opts[:surface],
+          ci_url: opts[:ci_url],
+          evidence_created: totals[:created],
+          evidence_updated: totals[:updated],
+          missing_marked_failing: totals[:missing_failing],
+          reports: totals[:reports]
+        }
+
+        output.success(data) do
+          puts "Ingested CI results for surface '#{opts[:surface]}':"
+          totals[:reports].each do |report|
+            report[:results].each do |r|
+              glyph = r['status'] == 'passing' ? '✓' : (r['status'] == 'failing' ? '✗' : '•')
+              puts "  #{glyph} #{r['slug']}  (#{r['status']})  #{r['source_file']}"
+            end
+          end
+          puts
+          puts "  created: #{totals[:created]}   updated: #{totals[:updated]}   marked failing (missing): #{totals[:missing_failing]}"
+        end
+      end
+    end
+  end
+end

data/lib/fp/commands/export.rb

@@ -0,0 +1,144 @@
+# frozen_string_literal: true
+
+module Fp
+  module Commands
+    # Renders every requirement in a project as a single Markdown document —
+    # title, status, category, surfaces, why/acceptance criteria, and an
+    # evidence summary per surface — nested parent/child like `fp list`.
+    #
+    # Unlike `fp matrix --csv` (a parity spreadsheet) this is meant to be read
+    # top to bottom: handed to a stakeholder, dropped in a repo's docs/, or
+    # attached to a release as a point-in-time record of what the product is
+    # supposed to do.
+    class Export < Base
+      KNOWN_FLAGS = {
+        project: :string,
+        status: :string,
+        category: :string,
+        surface: :string,
+        output: :string
+      }.freeze
+
+      def run(args)
+        opts, = parse_flags(args, KNOWN_FLAGS)
+        require_project!(opts)
+
+        project_id = resolve_project_id(opts[:project])
+
+        result = client.list_requirements(project_id: project_id, category: opts[:category])
+        unless result[:ok]
+          output.error(result[:error], status: result[:status])
+          exit 1
+        end
+
+        requirements = result[:data]['requirements'] || []
+
+        status_filter = opts[:status]
+        requirements = requirements.select { |r| r['status'] == status_filter } if status_filter
+
+        if opts[:surface]
+          requirements = requirements.select { |r| (r['required_surfaces'] || []).include?(opts[:surface]) }
+        end
+
+        document = render_document(opts[:project], requirements, project_id)
+
+        if opts[:output]
+          File.write(opts[:output], document)
+        end
+
+        output.success({ project: opts[:project], requirement_count: requirements.length, document: document }) do
+          if opts[:output]
+            puts "Wrote #{requirements.length} requirement(s) to #{opts[:output]}"
+          else
+            puts document
+          end
+        end
+      end
+
+      private
+
+      def render_document(project_slug, requirements, project_id)
+        lines = []
+        lines << "# Requirements: #{project_slug}"
+        lines << ''
+        lines << "_Generated #{Time.now.utc.strftime('%Y-%m-%d %H:%M UTC')} — #{requirements.length} requirement(s)._"
+        lines << ''
+
+        if requirements.empty?
+          lines << 'No requirements match the given filters.'
+          return lines.join("\n") + "\n"
+        end
+
+        parents = requirements.select { |r| r['parent_id'].nil? || r['parent_id'] == '' }
+        children_by_parent = requirements
+          .select { |r| r['parent_id'] && r['parent_id'] != '' }
+          .group_by { |r| r['parent_id'] }
+
+        parent_ids = parents.map { |p| p['id'] }.to_set
+        orphans = requirements.select { |r| r['parent_id'] && r['parent_id'] != '' && !parent_ids.include?(r['parent_id']) }
+
+        evidence_by_slug = fetch_evidence_by_slug(project_id, requirements)
+
+        parents.each do |req|
+          render_requirement(lines, req, evidence_by_slug[req['slug']], level: 2)
+          (children_by_parent[req['id']] || []).each do |child|
+            render_requirement(lines, child, evidence_by_slug[child['slug']], level: 3)
+          end
+        end
+
+        orphans.each { |req| render_requirement(lines, req, evidence_by_slug[req['slug']], level: 2) }
+
+        lines.join("\n") + "\n"
+      end
+
+      def render_requirement(lines, req, evidence, level:)
+        heading = '#' * level
+        lines << "#{heading} #{req['title']}"
+        lines << ''
+        lines << "- **Slug:** `#{req['slug']}`"
+        lines << "- **Status:** #{req['status']}"
+        lines << "- **Category:** #{req['category'] || '(none)'}"
+
+        surfaces = req['required_surfaces'] || []
+        lines << "- **Required Surfaces:** #{surfaces.empty? ? '(none)' : surfaces.join(', ')}"
+        lines << ''
+
+        if req['why'] && !req['why'].empty?
+          lines << '**Why:**'
+          lines << ''
+          lines << req['why']
+          lines << ''
+        end
+
+        if req['acceptance'] && !req['acceptance'].empty?
+          lines << '**Acceptance Criteria:**'
+          lines << ''
+          lines << req['acceptance']
+          lines << ''
+        end
+
+        lines << '**Evidence:**'
+        lines << ''
+        if evidence.nil? || evidence.empty?
+          lines << '_(none reported)_'
+        else
+          evidence.group_by { |e| e['surface'] }.each do |surface, records|
+            latest = records.max_by { |e| e['reported_at'].to_s }
+            lines << "- `#{surface}`: #{latest['status']}#{latest['reported_at'] ? " (as of #{latest['reported_at']})" : ''}"
+          end
+        end
+        lines << ''
+      end
+
+      # Evidence is keyed per-slug on the API, so fetch each requirement's records
+      # individually. Fine for a document export (infrequent, human-facing) rather
+      # than a hot path like `fp matrix`.
+      def fetch_evidence_by_slug(project_id, requirements)
+        requirements.each_with_object({}) do |req, memo|
+          result = client.list_evidence(project_id, slug: req['slug'])
+          memo[req['slug']] = result[:ok] ? (result[:data]['evidence'] || []) : []
+        end
+      end
+    end
+  end
+end