featureparity 0.0.17 → 0.0.18

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d20b326add84bbad1fc34a9b2b41c70216f7e9f2797f47cc9cba9f4293d27f1e
-  data.tar.gz: ae9721b86841174ee64f1925b0878e5ca5b5e34ea1f467ea0275887526515695
+  metadata.gz: c4c40ac26de064785c94120334d42b1e5e906803db09ad49e9954be91aa85ed3
+  data.tar.gz: a83874973a35ed0335c58f9fe49b71fb66f4a5ba97e028a806c34929f4e5718f
 SHA512:
-  metadata.gz: 87aa7b100433761979acec4c6a3f66c665757ebd77924cf1bab483861a1855be92acba93d3a6bd0e2f0cdc9daf9c887380a808eab96c467c3a41ee4e665f8bb0
-  data.tar.gz: 640c69700985e08ce0c6aec534d42d544db0d04771ae9f9be254e24aca3952cbbff7f52456c1c7b506c8bbf5e6a3d3b54c8c7959d6575d159d19cff5cad69c0b
+  metadata.gz: 75f833ce8cbf39c68a0ba50c12bee2f369d3d374ab3d8f2ce3468af433e18af6190b0d17a57a1e102fb1c58da80c8a0dbfea5d0f96bab78f0101f4f47c607aeb
+  data.tar.gz: 30c2e791fdefc1be0b83b13b4823b520d457dcd9c44adcd79b3f403525c338fc25dd73486f4b4388a7a43de641b7b81244116cdced8db5101330bc8b983b4888

data/lib/fp/cli.rb

@@ -13,6 +13,7 @@ module Fp
       'propose-change' => Commands::ProposeChange,
       'comment' => Commands::Comment,
       'history' => Commands::History,
+      'analyze' => Commands::Analyze,
       'changes' => Commands::Changes,
       'report' => Commands::Report,
       'ci-report' => Commands::CiReport,

data/lib/fp/client.rb

@@ -106,6 +106,21 @@ module Fp
       get("/api/projects/#{project_id}/requirement_changes", params)
     end
 
+    # GET /requirements/:id/analysis — the cached analysis, free to read. `analysis` is
+    # null when none exists or the wording changed since it ran (`stale` says which).
+    def get_requirement_analysis(requirement_id)
+      get("/api/requirements/#{requirement_id}/analysis")
+    end
+
+    # POST /requirements/:id/analyze — run (or return the still-current cached) analysis.
+    # One model call per requirement, which is what keeps it inside the request timeout.
+    def analyze_requirement(requirement_id, force: false, include_conflicts: false)
+      body = {}
+      body[:force] = true if force
+      body[:include_conflicts] = true if include_conflicts
+      post("/api/requirements/#{requirement_id}/analyze", body)
+    end
+
     # GET /requirements/:id/changes
     #
     # A requirement's change history: what it was, what changed, who changed it, and
@@ -274,15 +289,28 @@ module Fp
     end
 
     # POST /requirements/:requirement_id/attachments
-    # Confirm an upload and create the attachment record.
-    def create_attachment(requirement_id, attachment_id:, s3_key:, filename:, content_type:, size_bytes:)
-      post("/api/requirements/#{requirement_id}/attachments", {
+    # Confirm an upload and create the attachment record. Visual evidence may also
+    # carry the surface, capture time, observed deployment, and originating test run.
+    # evidence_key is a direct join to the evidence receipt (surface:repo:test_type).
+    def create_attachment(requirement_id, attachment_id:, s3_key:, filename:, content_type:, size_bytes:,
+                          surface: nil, captured_at: nil, deployed_at: nil, deployment_url: nil,
+                          test_run_url: nil, sha: nil, example_title: nil, evidence_key: nil)
+      body = {
         attachment_id: attachment_id,
         s3_key: s3_key,
         filename: filename,
         content_type: content_type,
         size_bytes: size_bytes
-      })
+      }
+      body[:surface] = surface if surface
+      body[:captured_at] = captured_at if captured_at
+      body[:deployed_at] = deployed_at if deployed_at
+      body[:deployment_url] = deployment_url if deployment_url
+      body[:test_run_url] = test_run_url if test_run_url
+      body[:sha] = sha if sha
+      body[:example_title] = example_title if example_title
+      body[:evidence_key] = evidence_key if evidence_key
+      post("/api/requirements/#{requirement_id}/attachments", body)
     end
 
     # GET /requirements/:requirement_id/attachments/:id
@@ -297,23 +325,24 @@ module Fp
       delete("/api/requirements/#{requirement_id}/attachments/#{attachment_id}")
     end
 
-    # Upload a file to S3 using a presigned URL.
-    # This is called after presign_attachment returns the upload_url.
+    # Upload to S3 using a streaming request. Video evidence can be up to 100 MB;
+    # reading it all into the CLI process would needlessly double memory usage.
     def upload_to_presigned_url(url, file_path, content_type)
       uri = URI.parse(url)
-      file_content = File.binread(file_path)
+      file_size = File.size(file_path)
 
       http = Net::HTTP.new(uri.host, uri.port)
       http.use_ssl = uri.scheme == 'https'
       http.open_timeout = 30
-      http.read_timeout = 120 # Allow longer for file upload
-
-      request = Net::HTTP::Put.new(uri)
-      request.body = file_content
-      request['Content-Type'] = content_type
-      request['Content-Length'] = file_content.bytesize.to_s
-
-      response = http.request(request)
+      http.read_timeout = 120
+
+      response = File.open(file_path, 'rb') do |file|
+        request = Net::HTTP::Put.new(uri)
+        request.body_stream = file
+        request['Content-Type'] = content_type
+        request['Content-Length'] = file_size.to_s
+        http.request(request)
+      end
       status = response.code.to_i
 
       if status >= 200 && status < 300

data/lib/fp/commands/analyze.rb

@@ -0,0 +1,213 @@
+# frozen_string_literal: true
+
+module Fp
+  module Commands
+    # `fp analyze [<slug>]` — a read-only triage sweep of requirement quality.
+    #
+    # Analysis is one model call per requirement, so this walks the catalog client-side,
+    # one request at a time, rather than asking the server to do it all in a single
+    # request (which cannot finish inside the API timeout on a real catalog). Results are
+    # cached server-side, so a requirement whose wording hasn't changed is read back for
+    # free and only new or edited ones cost a call — re-running the sweep is cheap.
+    #
+    # It never files anything. Proposing a change demotes the requirement to draft and
+    # marks its evidence suspect, so sweeping a catalog and proposing on every flag could
+    # put dozens of requirements up for review at once. The report says what *kind* of
+    # follow-up each finding suggests; a human picks which proposals get filed.
+    class Analyze < Base
+      KNOWN_FLAGS = {
+        project: :string,
+        status: :string,
+        conflicts: :boolean,
+        force: :boolean,
+        cached: :boolean
+      }.freeze
+
+      # Server-side findings that mean "this probably shouldn't be its own row".
+      REMOVAL_CHECKS = %w[is_focused_promise].freeze
+
+      ACTIONS = {
+        'conflict' => 'Stop and ask a human — two promises may contradict',
+        'propose_removal' => 'Consider `fp propose-change <slug> --removal` (duplicate, or a fragment of a broader promise)',
+        'needs_human' => 'Not clearly a product promise — a human decides whether it belongs',
+        'propose_change' => 'Consider `fp propose-change <slug>` to fix the wording',
+        'in_review' => 'A change is already awaiting review — skipped',
+        'not_analyzed' => 'No current analysis (run without --cached to analyze)',
+        'error' => 'Analysis failed',
+        'ok' => 'Nothing to act on'
+      }.freeze
+
+      ORDER = %w[conflict propose_removal needs_human propose_change in_review not_analyzed error ok].freeze
+
+      def run(args)
+        opts, positional = parse_flags(args, KNOWN_FLAGS)
+        require_project!(opts)
+
+        project_id = resolve_project_id(opts[:project])
+        requirements = select_requirements(project_id, positional.first, opts)
+
+        entries = requirements.map { |r| analyze_one(r, opts, requirements.length > 1) }
+        report = build_report(entries)
+
+        output.success(report) { print_report(report) }
+      end
+
+      private
+
+      def select_requirements(project_id, slug, opts)
+        result = client.list_requirements(project_id: project_id)
+        unless result[:ok]
+          output.error(result[:error], status: result[:status])
+          exit 1
+        end
+
+        all = result[:data]['requirements'] || []
+        if slug
+          found = all.select { |r| r['slug'] == slug }
+          if found.empty?
+            output.error("Requirement '#{slug}' not found in project")
+            exit 1
+          end
+          return found
+        end
+
+        statuses = (opts[:status] || 'active,draft').split(',').map(&:strip)
+        all.select { |r| statuses.include?(r['status']) }
+      end
+
+      def analyze_one(requirement, opts, sweeping)
+        slug = requirement['slug']
+        if requirement['pending_change_kind'].to_s != ''
+          return entry(requirement, 'in_review', nil)
+        end
+
+        progress("#{slug} ...") if sweeping
+        analysis = cached_analysis(requirement)
+
+        if analysis.nil? || opts[:force] || opts[:conflicts] && analysis['conflicts'].nil?
+          return entry(requirement, 'not_analyzed', nil) if opts[:cached]
+
+          result = client.analyze_requirement(requirement['id'], force: opts[:force],
+                                                                 include_conflicts: opts[:conflicts])
+          unless result[:ok]
+            # Without access (or without the analyzer) every call would fail the same way.
+            if [401, 402, 403, 503].include?(result[:status])
+              output.error(result[:error], status: result[:status])
+              exit 1
+            end
+            return entry(requirement, 'error', nil, error: result[:error])
+          end
+          analysis = result[:data]['analysis']
+        end
+
+        entry(requirement, classify(analysis), analysis)
+      end
+
+      # Free read of whatever is already cached and current; nil if there is none.
+      def cached_analysis(requirement)
+        result = client.get_requirement_analysis(requirement['id'])
+        result[:ok] ? result[:data]['analysis'] : nil
+      end
+
+      # Which kind of follow-up a finding suggests. Precedence matters: a possible
+      # contradiction outranks everything because it is a product decision, not an edit.
+      def classify(analysis)
+        return 'conflict' unless (analysis['conflicts'] || []).empty?
+
+        issues = analysis['issues'] || []
+        failed = failed_legitimacy_checks(analysis)
+
+        return 'propose_removal' if issues.any? { |i| i['type'] == 'duplicate' } ||
+                                    (failed & REMOVAL_CHECKS).any?
+        return 'needs_human' if analysis['verdict'] == 'questionable'
+        return 'propose_change' if analysis['verdict'] == 'needs_work' || !issues.empty?
+
+        'ok'
+      end
+
+      def failed_legitimacy_checks(analysis)
+        checks = analysis.dig('legitimacy', 'checks') || {}
+        checks.reject { |_name, c| c['passes'] }.keys
+      end
+
+      def entry(requirement, action, analysis, error: nil)
+        issues = (analysis && analysis['issues']) || []
+        {
+          'slug' => requirement['slug'],
+          'title' => requirement['title'],
+          'status' => requirement['status'],
+          'action' => action,
+          'verdict' => analysis && analysis['verdict'],
+          'failed_checks' => analysis ? failed_legitimacy_checks(analysis) : [],
+          'issues' => issues,
+          'duplicate_of' => issues.find { |i| i['type'] == 'duplicate' }&.dig('duplicate_of'),
+          'conflicts' => (analysis && analysis['conflicts']) || [],
+          'suggestions' => (analysis && analysis['suggestions']) || [],
+          'error' => error
+        }
+      end
+
+      def build_report(entries)
+        counts = entries.group_by { |e| e['action'] }.transform_values(&:length)
+        { 'analyzed' => entries.length, 'counts' => counts, 'requirements' => entries }
+      end
+
+      def print_report(report)
+        entries = report['requirements']
+        if entries.empty?
+          puts 'No requirements to analyze.'
+          return
+        end
+
+        if entries.length == 1
+          print_detail(entries.first)
+          return
+        end
+
+        puts "Analysis triage — #{entries.length} requirement(s). Nothing was proposed or changed."
+        puts
+
+        ORDER.each do |action|
+          group = entries.select { |e| e['action'] == action }
+          next if group.empty?
+
+          puts "#{action.tr('_', ' ').upcase} (#{group.length}) — #{ACTIONS[action]}"
+          next if action == 'ok'
+
+          group.each { |e| print_line(e) }
+          puts
+        end
+        puts
+        puts 'Report first; file only the proposals a human picks. Each proposal moves its requirement to draft.'
+      end
+
+      def print_line(entry)
+        puts "  #{entry['slug']} — #{truncate(entry['title'].to_s, 70)}"
+        puts "    superseded by: #{entry['duplicate_of']}" if entry['duplicate_of']
+        entry['conflicts'].each do |c|
+          puts "    conflicts with #{c['slug']} (#{(c['probability'].to_f * 100).round}%)"
+        end
+        puts "    fails: #{entry['failed_checks'].join(', ')}" unless entry['failed_checks'].empty?
+        puts "    issues: #{entry['issues'].map { |i| i['type'] }.join(', ')}" unless entry['issues'].empty?
+        puts "    error: #{entry['error']}" if entry['error']
+      end
+
+      def print_detail(entry)
+        puts "#{entry['slug']} — #{entry['title']}"
+        puts "  verdict: #{entry['verdict'] || '(none)'}   suggested: #{ACTIONS[entry['action']]}"
+        puts "  superseded by: #{entry['duplicate_of']}" if entry['duplicate_of']
+        puts "  fails: #{entry['failed_checks'].join(', ')}" unless entry['failed_checks'].empty?
+        entry['issues'].each { |i| puts "  issue: #{i['type']}" }
+        entry['conflicts'].each do |c|
+          puts "  conflict with #{c['slug']} (#{(c['probability'].to_f * 100).round}%): #{c['reason']}"
+        end
+        entry['suggestions'].each { |s| puts "  - #{s}" }
+        puts "  error: #{entry['error']}" if entry['error']
+      end
+
+      def progress(message)
+        warn message unless output.json?
+      end
+    end
+  end
+end

data/lib/fp/commands/attach.rb

@@ -4,186 +4,150 @@ require_relative 'base'
 
 module Fp
   module Commands
-    # Upload, list, and manage attachments on requirements.
-    #
-    # Usage:
-    #   fp attach <slug> <file>       Upload a file to a requirement
-    #   fp attachments <slug>         List attachments for a requirement
-    #   fp attachment <slug> <id>     Get download URL for an attachment
-    #   fp attachment rm <slug> <id>  Delete an attachment
+    # Upload visual test evidence or another supporting file to a requirement.
     class Attach < Base
-      # Allowed content types and their file extensions
       CONTENT_TYPES = {
-        'png' => 'image/png',
-        'jpg' => 'image/jpeg',
-        'jpeg' => 'image/jpeg',
-        'gif' => 'image/gif',
-        'webp' => 'image/webp',
-        'svg' => 'image/svg+xml',
-        'pdf' => 'application/pdf',
-        'txt' => 'text/plain',
-        'md' => 'text/markdown'
+        'png' => 'image/png', 'jpg' => 'image/jpeg', 'jpeg' => 'image/jpeg',
+        'gif' => 'image/gif', 'webp' => 'image/webp', 'svg' => 'image/svg+xml',
+        'mp4' => 'video/mp4', 'webm' => 'video/webm', 'mov' => 'video/quicktime',
+        'pdf' => 'application/pdf', 'txt' => 'text/plain', 'md' => 'text/markdown',
+        'json' => 'application/json'
+      }.freeze
+      VISUAL_EXTENSIONS = %w[png jpg jpeg gif webp mp4 webm mov].freeze
+      MAX_FILE_SIZE = 100 * 1024 * 1024
+      KNOWN_FLAGS = {
+        project: :string,
+        surface: :string,
+        captured_at: :string,
+        deployed_at: :string,
+        deployment_url: :string,
+        test_run_url: :string,
+        sha: :string,
+        example_title: :string,
+        evidence_key: :string
       }.freeze
-
-      MAX_FILE_SIZE = 10 * 1024 * 1024 # 10 MB
 
       def run(args)
-        case args[0]
-        when 'rm', 'delete'
-          delete_attachment(args[1..])
-        else
-          upload_attachment(args)
-        end
+        opts, positional = parse_flags(args, KNOWN_FLAGS)
+        return delete_attachment(opts, positional.drop(1)) if %w[rm delete].include?(positional.first)
+
+        upload_attachment(opts, positional)
       end
 
       private
 
-      def upload_attachment(args)
-        slug = args[0]
-        file_path = args[1]
+      def upload_attachment(opts, positional)
+        slug, file_path = positional
+        return usage_error('Missing requirement slug') if slug.to_s.empty?
+        return usage_error('Missing file path') if file_path.to_s.empty?
+        return command_error("File not found: #{file_path}") unless File.file?(file_path)
 
-        if slug.nil? || slug.empty?
-          Output.error('Missing requirement slug. Usage: fp attach <slug> <file>')
-          return 1
-        end
-
-        if file_path.nil? || file_path.empty?
-          Output.error('Missing file path. Usage: fp attach <slug> <file>')
-          return 1
-        end
-
-        unless File.exist?(file_path)
-          Output.error("File not found: #{file_path}")
-          return 1
-        end
-
-        project_id = require_project_id!
-        return 1 unless project_id
-
-        # Validate file
         filename = File.basename(file_path)
-        ext = File.extname(filename).delete('.').downcase
-        content_type = CONTENT_TYPES[ext]
-
+        extension = File.extname(filename).delete('.').downcase
+        content_type = CONTENT_TYPES[extension]
         unless content_type
-          Output.error("Unsupported file type: .#{ext}")
-          Output.info("Allowed: #{CONTENT_TYPES.keys.join(', ')}")
-          return 1
+          return command_error("Unsupported file type: .#{extension}. Allowed: #{CONTENT_TYPES.keys.join(', ')}")
         end
 
-        file_size = File.size(file_path)
-        if file_size > MAX_FILE_SIZE
-          Output.error("File too large: #{format_size(file_size)} (max #{format_size(MAX_FILE_SIZE)})")
-          return 1
+        size = File.size(file_path)
+        return command_error("File is empty: #{file_path}") if size.zero?
+        if size > MAX_FILE_SIZE
+          return command_error("File too large: #{format_size(size)} (max #{format_size(MAX_FILE_SIZE)})")
         end
-
-        # Resolve requirement
-        result = client.find_requirement_by_slug(project_id, slug)
-        unless result[:ok]
-          Output.error(result[:error])
-          return 1
+        if VISUAL_EXTENSIONS.include?(extension) && opts[:surface].to_s.empty?
+          return command_error('--surface is required for screenshot and video evidence')
         end
 
-        requirement = result[:data]['requirement']
-        requirement_id = requirement['id']
+        require_project!(opts)
+        project_id = resolve_project_id(opts[:project])
+        requirement_result = client.find_requirement_by_slug(project_id, slug)
+        return api_error(requirement_result) unless requirement_result[:ok]
 
-        # Step 1: Get presigned URL
-        Output.info("Requesting upload URL for #{filename}...")
+        requirement_id = requirement_result[:data].dig('requirement', 'id')
         presign_result = client.presign_attachment(
           requirement_id,
           filename: filename,
           content_type: content_type,
-          size_bytes: file_size
+          size_bytes: size
         )
+        return api_error(presign_result, prefix: 'Failed to get upload URL') unless presign_result[:ok]
 
-        unless presign_result[:ok]
-          Output.error("Failed to get upload URL: #{presign_result[:error]}")
-          return 1
-        end
-
-        presign_data = presign_result[:data]['presign']
-        upload_url = presign_data['upload_url']
-        attachment_id = presign_data['attachment_id']
-        s3_key = presign_data['s3_key']
-
-        # Step 2: Upload to S3
-        Output.info("Uploading #{filename} (#{format_size(file_size)})...")
-        upload_result = client.upload_to_presigned_url(upload_url, file_path, content_type)
-
-        unless upload_result[:ok]
-          Output.error("Upload failed: #{upload_result[:error]}")
-          return 1
-        end
+        presign = presign_result[:data]['presign']
+        upload_result = client.upload_to_presigned_url(presign['upload_url'], file_path, content_type)
+        return api_error(upload_result, prefix: 'Upload failed') unless upload_result[:ok]
 
-        # Step 3: Confirm upload
-        Output.info('Confirming upload...')
         create_result = client.create_attachment(
           requirement_id,
-          attachment_id: attachment_id,
-          s3_key: s3_key,
+          attachment_id: presign['attachment_id'],
+          s3_key: presign['s3_key'],
           filename: filename,
           content_type: content_type,
-          size_bytes: file_size
+          size_bytes: size,
+          surface: opts[:surface],
+          captured_at: opts[:captured_at],
+          deployed_at: opts[:deployed_at],
+          deployment_url: opts[:deployment_url],
+          test_run_url: opts[:test_run_url],
+          sha: opts[:sha],
+          example_title: opts[:example_title],
+          evidence_key: opts[:evidence_key]
         )
-
-        unless create_result[:ok]
-          Output.error("Failed to confirm upload: #{create_result[:error]}")
-          return 1
-        end
+        return api_error(create_result, prefix: 'Failed to confirm upload') unless create_result[:ok]
 
         attachment = create_result[:data]['attachment']
-        Output.success("Uploaded #{filename} to requirement '#{slug}'")
-        Output.info("  ID: #{attachment['id']}")
+        output.success({ attachment: attachment }) do
+          puts "Uploaded #{filename} to requirement '#{slug}'."
+          puts "  ID:           #{attachment['id']}"
+          puts "  Surface:      #{attachment['surface']}" if attachment['surface']
+          puts "  Test:         #{attachment['example_title']}" if attachment['example_title']
+          puts "  Evidence key: #{attachment['evidence_key']}" if attachment['evidence_key']
+          puts "  Captured:     #{attachment['captured_at']}" if attachment['captured_at']
+          puts "  Deploy:       #{attachment['deployment_url']}" if attachment['deployment_url']
+          puts '  Deployment context: unknown' if VISUAL_EXTENSIONS.include?(extension) && attachment['deployed_at'].to_s.empty?
+        end
         0
       end
 
-      def delete_attachment(args)
-        slug = args[0]
-        attachment_id = args[1]
+      def delete_attachment(opts, positional)
+        slug, attachment_id = positional
+        return usage_error('Missing requirement slug', delete: true) if slug.to_s.empty?
+        return usage_error('Missing attachment ID', delete: true) if attachment_id.to_s.empty?
 
-        if slug.nil? || slug.empty?
-          Output.error('Missing requirement slug. Usage: fp attachment rm <slug> <id>')
-          return 1
-        end
+        require_project!(opts)
+        project_id = resolve_project_id(opts[:project])
+        requirement_result = client.find_requirement_by_slug(project_id, slug)
+        return api_error(requirement_result) unless requirement_result[:ok]
 
-        if attachment_id.nil? || attachment_id.empty?
-          Output.error('Missing attachment ID. Usage: fp attachment rm <slug> <id>')
-          return 1
-        end
-
-        project_id = require_project_id!
-        return 1 unless project_id
-
-        # Resolve requirement
-        result = client.find_requirement_by_slug(project_id, slug)
-        unless result[:ok]
-          Output.error(result[:error])
-          return 1
-        end
+        requirement_id = requirement_result[:data].dig('requirement', 'id')
+        result = client.delete_attachment(requirement_id, attachment_id)
+        return api_error(result, prefix: 'Failed to delete attachment') unless result[:ok]
 
-        requirement = result[:data]['requirement']
-        requirement_id = requirement['id']
+        output.success({ id: attachment_id, deleted: true }) { puts "Deleted attachment #{attachment_id}." }
+        0
+      end
 
-        # Delete attachment
-        delete_result = client.delete_attachment(requirement_id, attachment_id)
+      def usage_error(message, delete: false)
+        usage = delete ? 'fp attach rm <slug> <id> [--project <project>]' :
+                         'fp attach <slug> <file> [--surface <surface>] [--project <project>]'
+        command_error("#{message}. Usage: #{usage}")
+      end
 
-        unless delete_result[:ok]
-          Output.error("Failed to delete attachment: #{delete_result[:error]}")
-          return 1
-        end
+      def api_error(result, prefix: nil)
+        message = [prefix, result[:error]].compact.join(': ')
+        output.error(message, status: result[:status])
+        1
+      end
 
-        Output.success("Deleted attachment #{attachment_id}")
-        0
+      def command_error(message)
+        output.error(message)
+        1
       end
 
       def format_size(bytes)
-        if bytes >= 1024 * 1024
-          format('%.1f MB', bytes.to_f / (1024 * 1024))
-        elsif bytes >= 1024
-          format('%.1f KB', bytes.to_f / 1024)
-        else
-          "#{bytes} bytes"
-        end
+        return format('%.1f MB', bytes.to_f / (1024 * 1024)) if bytes >= 1024 * 1024
+        return format('%.1f KB', bytes.to_f / 1024) if bytes >= 1024
+
+        "#{bytes} bytes"
       end
     end
   end

data/lib/fp/commands/attachments.rb

@@ -4,118 +4,91 @@ require_relative 'base'
 
 module Fp
   module Commands
-    # List attachments for a requirement, or get a download URL for one.
-    #
-    # Usage:
-    #   fp attachments <slug>         List attachments for a requirement
-    #   fp attachments <slug> <id>    Get download URL for an attachment
+    # List a requirement's attachments, or get a short-lived URL for one.
     class Attachments < Base
-      def run(args)
-        slug = args[0]
-        attachment_id = args[1]
-
-        if slug.nil? || slug.empty?
-          Output.error('Missing requirement slug. Usage: fp attachments <slug> [<id>]')
-          return 1
-        end
+      KNOWN_FLAGS = { project: :string }.freeze
 
-        project_id = require_project_id!
-        return 1 unless project_id
-
-        # Resolve requirement
-        result = client.find_requirement_by_slug(project_id, slug)
-        unless result[:ok]
-          Output.error(result[:error])
+      def run(args)
+        opts, positional = parse_flags(args, KNOWN_FLAGS)
+        slug, attachment_id = positional
+        if slug.to_s.empty?
+          output.error('Missing requirement slug. Usage: fp attachments <slug> [<id>] [--project <project>]')
           return 1
         end
 
-        requirement = result[:data]['requirement']
-        requirement_id = requirement['id']
+        require_project!(opts)
+        project_id = resolve_project_id(opts[:project])
+        requirement_result = client.find_requirement_by_slug(project_id, slug)
+        return api_error(requirement_result) unless requirement_result[:ok]
 
-        if attachment_id
-          show_attachment(requirement_id, attachment_id, slug)
-        else
-          list_attachments(requirement_id, slug)
-        end
+        requirement_id = requirement_result[:data].dig('requirement', 'id')
+        attachment_id ? show_attachment(requirement_id, attachment_id) : list_attachments(requirement_id, slug)
       end
 
       private
 
       def list_attachments(requirement_id, slug)
         result = client.list_attachments(requirement_id)
-
-        unless result[:ok]
-          Output.error(result[:error])
-          return 1
-        end
+        return api_error(result) unless result[:ok]
 
         attachments = result[:data]['attachments'] || []
-
-        if json_output?
-          Output.json({ attachments: attachments })
-          return 0
-        end
-
-        if attachments.empty?
-          Output.info("No attachments for requirement '#{slug}'")
-          return 0
-        end
-
-        Output.info("Attachments for '#{slug}':\n")
-        attachments.each do |att|
-          puts "  #{att['id']}"
-          puts "    Filename: #{att['filename']}"
-          puts "    Type: #{att['content_type']}"
-          puts "    Size: #{format_size(att['size_bytes'])}"
-          puts "    Uploaded by: #{att['uploaded_by']}"
-          puts "    Uploaded at: #{att['created_at']}"
-          puts
+        output.success({ attachments: attachments }) do
+          if attachments.empty?
+            puts "No attachments for requirement '#{slug}'."
+          else
+            puts "Attachments for '#{slug}':"
+            attachments.each do |attachment|
+              puts
+              puts "  #{attachment['id']}  #{attachment['filename']} (#{format_size(attachment['size_bytes'])})"
+              puts "    Surface:    #{attachment['surface']}" if attachment['surface']
+              puts "    Captured:   #{attachment['captured_at']}" if attachment['captured_at']
+              puts "    Deployment: #{deployment_label(attachment)}"
+              puts "    Test run:   #{attachment['test_run_url']}" if attachment['test_run_url']
+            end
+          end
         end
-
         0
       end
 
-      def show_attachment(requirement_id, attachment_id, slug)
+      def show_attachment(requirement_id, attachment_id)
         result = client.get_attachment(requirement_id, attachment_id)
-
-        unless result[:ok]
-          Output.error(result[:error])
-          return 1
-        end
+        return api_error(result) unless result[:ok]
 
         data = result[:data]['attachment_response'] || result[:data]
         attachment = data['attachment']
-        download_url = data['download_url']
-        expires_in = data['expires_in']
-
-        if json_output?
-          Output.json(data)
-          return 0
+        output.success(data) do
+          puts "Attachment: #{attachment['filename']}"
+          puts "  Type:       #{attachment['content_type']}"
+          puts "  Size:       #{format_size(attachment['size_bytes'])}"
+          puts "  Surface:    #{attachment['surface']}" if attachment['surface']
+          puts "  Captured:   #{attachment['captured_at']}" if attachment['captured_at']
+          puts "  Deployment: #{deployment_label(attachment)}"
+          puts
+          puts "View URL (expires in #{data['expires_in'].to_i / 60} minutes):"
+          puts data['download_url']
         end
+        0
+      end
 
-        Output.info("Attachment: #{attachment['filename']}")
-        puts "  ID: #{attachment['id']}"
-        puts "  Type: #{attachment['content_type']}"
-        puts "  Size: #{format_size(attachment['size_bytes'])}"
-        puts "  Uploaded by: #{attachment['uploaded_by']}"
-        puts "  Uploaded at: #{attachment['created_at']}"
-        puts
-        puts "Download URL (expires in #{expires_in / 60} minutes):"
-        puts download_url
+      def deployment_label(attachment)
+        case attachment['deployment_status']
+        when 'after_deployment' then "captured after deploy#{" at #{attachment['deployed_at']}" if attachment['deployed_at']}"
+        when 'predates_deployment' then "capture predates deploy#{" at #{attachment['deployed_at']}" if attachment['deployed_at']}"
+        else 'unknown'
+        end
+      end
 
-        0
+      def api_error(result)
+        output.error(result[:error], status: result[:status])
+        1
       end
 
       def format_size(bytes)
-        return '0 bytes' if bytes.nil? || bytes.zero?
+        bytes = bytes.to_i
+        return format('%.1f MB', bytes.to_f / (1024 * 1024)) if bytes >= 1024 * 1024
+        return format('%.1f KB', bytes.to_f / 1024) if bytes >= 1024
 
-        if bytes >= 1024 * 1024
-          format('%.1f MB', bytes.to_f / (1024 * 1024))
-        elsif bytes >= 1024
-          format('%.1f KB', bytes.to_f / 1024)
-        else
-          "#{bytes} bytes"
-        end
+        "#{bytes} bytes"
       end
     end
   end

data/lib/fp/commands/help.rb

@@ -24,6 +24,7 @@ module Fp
             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
@@ -267,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/report.rb

@@ -86,7 +86,7 @@ module Fp
         params[:work_item_url] = opts[:work_item] if opts[:work_item]
         params[:ci_url] = opts[:ci_url] if opts[:ci_url]
         params[:title] = opts[:title] if opts[:title]
-        params[:line] = opts[:line] if opts[:line]
+        params[:line] = opts[:line].to_i if opts[:line]
 
         # Try to report evidence
         result = client.report_evidence(params)

data/lib/fp/commands.rb

@@ -9,6 +9,7 @@ require_relative 'commands/propose'
 require_relative 'commands/propose_change'
 require_relative 'commands/comment'
 require_relative 'commands/history'
+require_relative 'commands/analyze'
 require_relative 'commands/changes'
 require_relative 'commands/report'
 require_relative 'commands/ci_report'

data/lib/fp/version.rb

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

data/skills/fp/SKILL.md

@@ -350,6 +350,37 @@ FeatureParity section in `AGENTS.md`):
 fp init --project <slug> --surface <surface>
 ```
 
+### Triage requirement quality (`fp analyze`)
+
+`fp analyze` checks how well requirements are written and whether they belong in the
+catalog at all. It is **read-only: it never proposes anything.** Sweep first, report, and
+only file the proposals a human picks — every proposal moves its requirement back to draft
+and marks its evidence `suspect`, and a requirement holds one open proposal at a time, so
+proposing on every flag could put dozens of requirements in review at once.
+
+```bash
+fp analyze --project stowzilla                    # sweep active + draft requirements
+fp analyze print_container_qr --project stowzilla # one requirement, with suggestions
+fp analyze --project stowzilla --conflicts        # also check for contradictions (slower)
+fp analyze --project stowzilla --cached           # read saved results only, no model calls
+fp analyze --project stowzilla --json
+```
+
+It goes one requirement at a time. Results are cached until the wording changes, so a
+re-run only pays for requirements that are new or edited. Requirements with a change
+already awaiting review are skipped.
+
+Each finding suggests a kind of follow-up. Treat it as a signal that something is wrong,
+not as the fix — you still write the proposal.
+
+| Finding | Suggested follow-up |
+|---------|---------------------|
+| Possible conflict with another requirement | Stop and ask a human — a contradiction is a product decision. Read both requirements first; the analyzer says *that* they clash, not *why* |
+| Duplicate (the report names `superseded by: <slug>`) | `fp propose-change <slug> --removal --reason "superseded by <other>"` |
+| Fragment of a broader promise (`is_focused_promise` fails) | Fold it into the parent's acceptance: `fp propose-change <parent>` for the wording, then `--removal` for the fragment |
+| Not a product promise / not observable | A human decides whether it belongs; don't guess |
+| Missing why, vague acceptance, implementation detail, boilerplate | `fp propose-change <slug> --why "..." --acceptance "..."` |
+
 ## Quick reference
 
 | Task | Command |
@@ -364,6 +395,7 @@ fp init --project <slug> --surface <surface>
 | Propose a change | `fp propose-change <slug> --project X --why "..." --reason "..."` |
 | Propose a deletion | `fp propose-change <slug> --project X --removal --reason "..."` |
 | View change history | `fp history <slug> --project X` |
+| Triage requirement quality | `fp analyze --project X` |
 | View work-item activity | `fp changes --project X --source-url URL` |
 | Enforce parity | `fp check --project X` |
 | Gate on this run | `fp check --project X --surface Y --junit file.xml` |

data/skills/fp/references/cli.md

@@ -276,6 +276,37 @@ the review decision where one was made. An open proposal is called out at the en
 
 `--project` is optional when the repo has a `.featureparity.yml`.
 
+### fp analyze
+
+Triage requirement quality: duplicates, fragments of a broader promise, vague wording,
+possible conflicts. **Read-only — it never files a proposal.** Report first; a human
+picks which proposals to file (each moves its requirement to draft).
+
+```bash
+fp analyze --project stowzilla                     # active + draft requirements
+fp analyze print_container_qr --project stowzilla  # one requirement, with suggestions
+fp analyze --project stowzilla --status active     # narrow the sweep
+fp analyze --project stowzilla --conflicts         # also check contradictions (slower)
+fp analyze --project stowzilla --force             # re-run even if the result is current
+fp analyze --project stowzilla --cached            # saved results only, no model calls
+fp analyze --project stowzilla --json
+```
+
+Analysis costs one model call per requirement, so the sweep runs one request at a time
+rather than asking the server to do the whole catalog at once (which cannot finish inside
+the API timeout). Results are cached until a requirement's title, why, or acceptance
+changes, so re-running only pays for new or edited requirements. A requirement with a
+change awaiting review is skipped.
+
+The report groups findings by suggested follow-up: **conflict** (ask a human),
+**propose removal** (duplicate — with `superseded by: <slug>` — or a fragment of a broader
+promise), **needs human** (not clearly a product promise), **propose change** (wording
+issues), plus in-review, not-analyzed (`--cached` only), and error. `--conflicts` adds
+the other requirement's slug, a probability, and both acceptance clauses side by side —
+the analyzer flags the clash but cannot explain it.
+
+`--project` is optional when the repo has a `.featureparity.yml`.
+
 ### fp changes
 
 Show requirement activity prompted by a work item, rather than opening every requirement's

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: featureparity
 version: !ruby/object:Gem::Version
-  version: 0.0.17
+  version: 0.0.18
 platform: ruby
 authors:
 - Stowzilla
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-10-14 00:00:00.000000000 Z
+date: 2026-10-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: net-http
@@ -94,6 +94,7 @@ files:
 - lib/fp/cli.rb
 - lib/fp/client.rb
 - lib/fp/commands.rb
+- lib/fp/commands/analyze.rb
 - lib/fp/commands/attach.rb
 - lib/fp/commands/attachments.rb
 - lib/fp/commands/base.rb