featureparity 0.0.27 → 0.0.29

data/lib/fp/commands/propose.rb

@@ -1,12 +1,22 @@
 # frozen_string_literal: true
 
+require 'yaml'
+require_relative '../requirement_lint'
+
 module Fp
   module Commands
     # fp propose --project <slug> --slug X --name "..." --why "..." --required a,b,c --required-types unit,e2e --acceptance "..." --parent <slug> --category <cat>
-    # Create a new requirement as draft
+    # fp propose --file requirements.yml [--dry-run]
+    # Create a new requirement as draft — one from flags, or a batch from a file.
+    #
+    # --dry-run validates and lints without writing (Fizzy #1786): an agent can check its
+    # wording, and a human can review a whole batch, before anything lands in the catalog.
+    # --file validates every entry first — slugs, parents, categories, source types,
+    # collisions with the catalog — and writes nothing if any of them is wrong.
     class Propose < Base
       help_summary 'Propose a new requirement (created as a draft; a human activates it)'
-      help_usage 'fp propose --project <slug> --slug <key> --name "..." [flags]'
+      help_usage 'fp propose --project <slug> --slug <key> --name "..." [flags]',
+                 'fp propose --file requirements.yml [--dry-run]'
       help_flag :project, 'Project slug (falls back to .featureparity.yml)'
       help_flag :slug, 'Initial key for the requirement', required: true
       help_flag :name, 'Human-readable title (one product promise, present tense)', required: true
@@ -17,11 +27,20 @@ module Fp
       help_flag :parent, "Parent requirement's slug (nests one level; subset of parent's surfaces)"
       help_flag :category, 'One of: functional, non-functional, ux, performance, security, compliance'
       help_flag :tags, 'Comma-separated free-form labels'
-      help_flag :source_type, 'Where it came from: fizzy, discord, github_issue, jira, notion, manual, ai_chat'
+      help_flag :source_type, 'Where it came from: fizzy, discord, github_issue, jira, notion, manual, ai_chat, repo_scan (an agent read the code)'
       help_flag :source_url, 'URL of the originating card/issue/thread'
       help_flag :source_context, 'Free-form note about the origin'
+      help_flag :source_ref, 'A place in the repo it was read from, e.g. app/models/order.rb:42 (repeatable)'
+      help_flag :file, 'YAML or JSON file of requirements to propose in one batch (validated all-or-nothing)'
+      help_flag :dry_run, 'Validate and lint the wording; write nothing'
       help_example 'fp propose --project stowzilla --slug print_qr --name "Print QR on container label" --why "Staff mis-type the ID without a scannable code" --required api,customer_ios --acceptance "QR scans to the container detail page"'
-      help_note 'Agents can only create drafts. A human activates it in the web app.'
+      help_example 'fp propose --file requirements.yml --dry-run', 'Lint a batch and show what would be created'
+      help_example 'fp propose --file requirements.yml --source-type repo_scan', 'Create the batch; flags are defaults for every entry'
+      help_note "Agents can only create drafts. A human activates it in the web app.\n" \
+                "A --file holds `requirements:` (a list of entries with slug, name, why, acceptance,\n" \
+                "required, required_types, parent, category, tags, source_type, source_url,\n" \
+                "source_context, source_refs) and optional `defaults:` merged into every entry.\n" \
+                'A parent may be another entry in the same file; it is created first.'
 
       KNOWN_FLAGS = {
         project: :string,
@@ -36,70 +55,46 @@ module Fp
         source_type: :string,
         source_url: :string,
         source_context: :string,
-        tags: :string
+        tags: :string,
+        file: :string,
+        dry_run: :boolean
       }.freeze
 
       VALID_CATEGORIES = %w[functional non-functional ux performance security compliance].freeze
-      VALID_SOURCE_TYPES = %w[fizzy discord github_issue jira notion manual ai_chat].freeze
+      VALID_SOURCE_TYPES = %w[fizzy discord github_issue jira notion manual ai_chat repo_scan].freeze
+
+      # Keys an entry in a --file may carry. Anything else is refused, so a typo like
+      # `acceptence` fails the batch instead of silently dropping the criteria.
+      FILE_KEYS = %w[slug name title why acceptance required required_surfaces required_types
+                     required_test_types parent category tags source_type source_url
+                     source_context source_refs].freeze
 
       def run(args)
+        source_refs, args = extract_repeated(args, '--source-ref')
         opts, = parse_flags(args, KNOWN_FLAGS)
-
         require_project!(opts)
+
+        return run_batch(opts, source_refs) if opts[:file]
+
         require_flag(opts, :slug, '--slug is required (initial key for the requirement)')
         require_flag(opts, :name, '--name is required (human-readable title)')
 
-        # Validate category client-side for better UX (fail fast with helpful message)
-        if opts[:category] && !VALID_CATEGORIES.include?(opts[:category])
-          output.error("Invalid category '#{opts[:category]}'. Must be one of: #{VALID_CATEGORIES.join(', ')}")
+        spec = spec_from_flags(opts, source_refs)
+        errors = validate_spec(spec)
+        unless errors.empty?
+          errors.each { |e| output.error(e) }
           exit 1
         end
 
-        if 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
-
-        # Parse and validate required test types (comma-separated).
-        required_test_types = parse_test_types(opts[:required_types])
-
         project_id = resolve_project_id(opts[:project])
+        return dry_run_single(spec, project_id) if opts[:dry_run]
 
-        # Parse required surfaces (comma-separated)
-        required_surfaces = if opts[:required]
-                              opts[:required].split(',').map(&:strip)
-                            else
-                              []
-                            end
-
-        params = {
-          slug: opts[:slug],
-          title: opts[:name],
-          project_id: project_id,
-          required_surfaces: required_surfaces
-        }
-        params[:required_test_types] = required_test_types unless required_test_types.empty?
-        params[:why] = opts[:why] if opts[:why]
-        params[:acceptance] = opts[:acceptance] if opts[:acceptance]
-        params[:category] = opts[:category] if opts[:category]
-        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]
-
-        # Tags are comma-separated. Send the raw list — the API normalizes
-        # (downcase/trim/dedupe) and validates.
-        if opts[:tags]
-          params[:tags] = opts[:tags].split(',').map(&:strip).reject(&:empty?)
-        end
-
-        # Resolve parent slug to parent_id if provided
-        if opts[:parent]
-          parent_id = resolve_parent_id(project_id, opts[:parent])
-          params[:parent_id] = parent_id
-        end
+        params = params_for(spec, project_id)
+        params[:parent_id] = resolve_parent_id(project_id, spec[:parent]) if spec[:parent]
 
+        lint_warnings(spec)
         # Note: status is NOT sent - the API enforces draft for agents
-
+        warn_if_not_production!
         result = client.create_requirement(params)
 
         unless result[:ok]
@@ -108,8 +103,10 @@ module Fp
         end
 
         requirement = result[:data]['requirement']
+        feedback = draft_feedback(requirement)
+        data = result[:data].merge('analysis' => feedback[:analysis], 'analysis_error' => feedback[:error]).compact
 
-        output.success(result[:data]) do
+        output.success(data) do
           puts "Created requirement '#{requirement['slug']}' as DRAFT."
           puts
           puts "  Title:    #{requirement['title']}"
@@ -120,16 +117,401 @@ module Fp
           unless (requirement['required_test_types'] || []).empty?
             puts "  Test types: #{(requirement['required_test_types'] || []).join(', ')} (each must have evidence on every surface)"
           end
-          puts "  Parent:   #{opts[:parent] || '(none)'}" if opts[:parent]
+          puts "  Parent:   #{spec[:parent] || '(none)'}" if spec[:parent]
           puts
           puts '⚠️  This requirement is a DRAFT.'
           puts '   A human must activate it in the web app before it appears in the parity matrix.'
           puts '   Agents cannot activate requirements.'
+          print_feedback(feedback, requirement['slug'])
         end
       end
 
       private
 
+      # --- Building and checking a spec ---------------------------------------------
+
+      # A requirement to propose, normalized from flags or a file entry.
+      def spec_from_flags(opts, source_refs)
+        {
+          slug: opts[:slug],
+          title: opts[:name],
+          why: opts[:why],
+          acceptance: opts[:acceptance],
+          required_surfaces: split_list(opts[:required]),
+          required_test_types: parse_test_types(opts[:required_types]),
+          parent: opts[:parent],
+          category: opts[:category],
+          tags: split_list(opts[:tags]),
+          source_type: opts[:source_type],
+          source_url: opts[:source_url],
+          source_context: opts[:source_context],
+          source_refs: source_refs.map(&:strip).reject(&:empty?)
+        }
+      end
+
+      def validate_spec(spec)
+        errors = []
+        errors << '--slug is required (initial key for the requirement)' if blank?(spec[:slug])
+        errors << '--name is required (human-readable title)' if blank?(spec[:title])
+        # Validated client-side for better UX (fail fast with the valid list).
+        if spec[:category] && !VALID_CATEGORIES.include?(spec[:category])
+          errors << "Invalid category '#{spec[:category]}'. Must be one of: #{VALID_CATEGORIES.join(', ')}"
+        end
+        if spec[:source_type] && !VALID_SOURCE_TYPES.include?(spec[:source_type])
+          errors << "Invalid source type '#{spec[:source_type]}'. Must be one of: #{VALID_SOURCE_TYPES.join(', ')}"
+        end
+        if spec[:source_refs].any? { |r| r.include?("\n") }
+          errors << 'Each --source-ref must be a single line, e.g. app/models/order.rb:42'
+        end
+        errors
+      end
+
+      def params_for(spec, project_id)
+        params = {
+          slug: spec[:slug],
+          title: spec[:title],
+          project_id: project_id,
+          required_surfaces: spec[:required_surfaces]
+        }
+        params[:required_test_types] = spec[:required_test_types] unless spec[:required_test_types].empty?
+        %i[why acceptance category source_type source_url source_context].each do |key|
+          params[key] = spec[key] if spec[key]
+        end
+        params[:source_refs] = spec[:source_refs] unless spec[:source_refs].empty?
+        # Send the raw list — the API normalizes (downcase/trim/dedupe) and validates.
+        params[:tags] = spec[:tags] unless spec[:tags].empty?
+        params
+      end
+
+      def lint_for(spec)
+        RequirementLint.check(spec).map { |f| { 'field' => f.field, 'message' => f.message } }
+      end
+
+      # Wording notes on stderr, so the human output reads as before and --json stays clean.
+      def lint_warnings(spec)
+        notes = lint_for(spec)
+        return if notes.empty?
+
+        $stderr.puts "Wording notes for '#{spec[:slug]}' (run with --dry-run to check before writing):"
+        notes.each { |n| $stderr.puts "  - #{n['field']} #{n['message']}" }
+      end
+
+      # --- Dry run -------------------------------------------------------------------
+
+      def dry_run_single(spec, project_id)
+        existing = catalog(project_id)
+        problems = catalog_problems([spec], existing)
+        lint = lint_for(spec)
+        data = { dry_run: true, valid: problems.empty?, requirement: preview_params(spec), problems: problems, lint: lint }
+
+        output.success(data) do
+          puts "Dry run — nothing was written. fp propose would create '#{spec[:slug]}' as a DRAFT:"
+          print_preview(spec)
+          print_problems(problems)
+          print_lint(spec[:slug], lint)
+        end
+        exit 1 unless problems.empty?
+      end
+
+      def preview_params(spec)
+        params_for(spec, nil).reject { |k, _| k == :project_id }.merge(parent: spec[:parent]).compact
+      end
+
+      def print_preview(spec)
+        puts "  Title:      #{spec[:title]}"
+        puts "  Surfaces:   #{spec[:required_surfaces].join(', ')}" unless spec[:required_surfaces].empty?
+        puts "  Test types: #{spec[:required_test_types].join(', ')}" unless spec[:required_test_types].empty?
+        puts "  Parent:     #{spec[:parent]}" if spec[:parent]
+        puts "  Category:   #{spec[:category]}" if spec[:category]
+        puts "  Why:        #{spec[:why]}" if spec[:why]
+        puts "  Acceptance: #{spec[:acceptance]}" if spec[:acceptance]
+        source = [spec[:source_type], spec[:source_url]].compact.join(' ')
+        puts "  Source:     #{source}" unless source.empty?
+        spec[:source_refs].each { |r| puts "              #{r}" }
+      end
+
+      def print_problems(problems)
+        return if problems.empty?
+
+        puts
+        puts "✗ #{problems.length} problem(s) would stop this from being created:"
+        problems.each { |p| puts "  - #{p}" }
+      end
+
+      def print_lint(slug, lint)
+        puts
+        if lint.empty?
+          puts "✓ No wording notes for '#{slug}'."
+        else
+          puts "Wording notes for '#{slug}' (advice, not errors — a human decides):"
+          lint.each { |n| puts "  - #{n['field']} #{n['message']}" }
+        end
+      end
+
+      # --- Batch from a file ----------------------------------------------------------
+
+      def run_batch(opts, flag_refs)
+        entries = load_entries(opts[:file])
+        defaults = spec_from_flags(opts.merge(slug: nil, name: nil), flag_refs)
+
+        specs = []
+        errors = []
+        entries[:list].each_with_index do |entry, i|
+          label = "entry #{i + 1}#{entry.is_a?(Hash) && entry['slug'] ? " (#{entry['slug']})" : ''}"
+          unless entry.is_a?(Hash)
+            errors << "#{label}: must be a mapping of fields, got #{entry.class}"
+            next
+          end
+
+          merged = entries[:defaults].merge(entry)
+          unknown = merged.keys - FILE_KEYS
+          errors << "#{label}: unknown field(s) #{unknown.join(', ')} (allowed: #{FILE_KEYS.join(', ')})" unless unknown.empty?
+
+          spec = spec_from_entry(merged, defaults)
+          validate_spec(spec).each { |e| errors << "#{label}: #{e.sub(/\A--(slug|name) is required.*/) { "#{Regexp.last_match(1)} is required" }}" }
+          specs << spec
+        end
+
+        if specs.empty? && errors.empty?
+          output.error("#{opts[:file]} has no requirements to propose")
+          exit 1
+        end
+
+        unless errors.empty?
+          summary = "#{opts[:file]}: #{errors.length} problem(s); nothing was created."
+          if output.json?
+            output.error("#{summary} #{errors.join('; ')}")
+          else
+            output.error(summary)
+            errors.each { |e| warn "  #{e}" }
+          end
+          exit 1
+        end
+
+        project_id = resolve_project_id(opts[:project])
+        existing = catalog(project_id)
+        problems = catalog_problems(specs, existing)
+        ordered = parents_first(specs)
+        lint = ordered.to_h { |s| [s[:slug], lint_for(s)] }
+
+        if opts[:dry_run] || !problems.empty?
+          data = { dry_run: !!opts[:dry_run], valid: problems.empty?, problems: problems,
+                   requirements: ordered.map { |s| preview_params(s).merge(lint: lint[s[:slug]]) } }
+          output.success(data) do
+            heading = opts[:dry_run] ? 'Dry run — nothing was written.' : 'Nothing was created.'
+            puts "#{heading} #{ordered.length} requirement(s) in #{opts[:file]}:"
+            print_batch_table(ordered, lint)
+            print_problems(problems)
+            print_batch_lint(ordered, lint)
+          end
+          exit 1 unless problems.empty?
+          return
+        end
+
+        warn_if_not_production!
+        create_batch(ordered, project_id, existing, lint, opts)
+      end
+
+      def load_entries(path)
+        unless File.file?(path)
+          output.error("No such file: #{path}")
+          exit 1
+        end
+
+        doc = begin
+          YAML.safe_load(File.read(path), aliases: false)
+        rescue Psych::Exception => e
+          output.error("Could not parse #{path}: #{e.message}")
+          exit 1
+        end
+
+        case doc
+        when Array
+          { list: doc, defaults: {} }
+        when Hash
+          defaults = doc['defaults'] || {}
+          unless doc['requirements'].is_a?(Array) && defaults.is_a?(Hash)
+            output.error("#{path} must hold a `requirements:` list (and optionally a `defaults:` mapping), or be a list")
+            exit 1
+          end
+          { list: doc['requirements'], defaults: defaults.transform_keys(&:to_s) }
+        else
+          output.error("#{path} must hold a `requirements:` list, or be a list")
+          exit 1
+        end
+      end
+
+      # A file entry wins over its `defaults:`, which win over the command's flags.
+      def spec_from_entry(entry, flag_defaults)
+        list = ->(v) { v.is_a?(Array) ? v.map { |x| x.to_s.strip }.reject(&:empty?) : split_list(v&.to_s) }
+        fetch = ->(*keys) { keys.map { |k| entry[k] }.find { |v| !v.nil? } }
+        str = ->(*keys) { v = fetch.call(*keys); v.nil? ? nil : v.to_s }
+
+        refs = fetch.call('source_refs')
+        types = fetch.call('required_types', 'required_test_types')
+        surfaces = fetch.call('required', 'required_surfaces')
+        tags = fetch.call('tags')
+        {
+          slug: str.call('slug'),
+          title: str.call('name', 'title'),
+          why: str.call('why'),
+          acceptance: str.call('acceptance'),
+          required_surfaces: surfaces.nil? ? flag_defaults[:required_surfaces] : list.call(surfaces),
+          required_test_types: types.nil? ? flag_defaults[:required_test_types] : list.call(types).map(&:downcase).uniq,
+          parent: str.call('parent') || flag_defaults[:parent],
+          category: str.call('category') || flag_defaults[:category],
+          tags: tags.nil? ? flag_defaults[:tags] : list.call(tags),
+          source_type: str.call('source_type') || flag_defaults[:source_type],
+          source_url: str.call('source_url') || flag_defaults[:source_url],
+          source_context: str.call('source_context') || flag_defaults[:source_context],
+          source_refs: refs.nil? ? flag_defaults[:source_refs] : Array(refs).map { |r| r.to_s.strip }.reject(&:empty?)
+        }
+      end
+
+      # Problems only the catalog can reveal: a slug already taken, a parent that
+      # doesn't exist or is itself a child (nesting is one level), and duplicates
+      # within the batch.
+      def catalog_problems(specs, existing)
+        by_slug = existing.to_h { |r| [r['slug'], r] }
+        in_batch = specs.to_h { |s| [s[:slug], s] }
+        problems = []
+
+        specs.group_by { |s| s[:slug] }.each do |slug, group|
+          problems << "'#{slug}' appears #{group.length} times in the batch" if group.length > 1
+        end
+
+        specs.each do |spec|
+          problems << "'#{spec[:slug]}' already exists in this project (#{by_slug[spec[:slug]]['status']})" if by_slug.key?(spec[:slug])
+          next unless spec[:parent]
+
+          if (parent = in_batch[spec[:parent]])
+            if parent[:parent]
+              problems << "'#{spec[:slug]}' names parent '#{spec[:parent]}', which is itself a child — requirements nest one level"
+            end
+          elsif (parent = by_slug[spec[:parent]])
+            unless blank?(parent['parent_id'])
+              problems << "'#{spec[:slug]}' names parent '#{spec[:parent]}', which is itself a child — requirements nest one level"
+            end
+          else
+            problems << "'#{spec[:slug]}' names parent '#{spec[:parent]}', which is neither in this project nor in the batch"
+          end
+        end
+        problems
+      end
+
+      # Entries whose parent is another entry go after it.
+      def parents_first(specs)
+        batch_slugs = specs.map { |s| s[:slug] }
+        top, children = specs.partition { |s| s[:parent].nil? || !batch_slugs.include?(s[:parent]) }
+        top + children
+      end
+
+      def create_batch(ordered, project_id, existing, lint, opts)
+        ids = existing.to_h { |r| [r['slug'], r['id']] }
+        created = []
+
+        ordered.each do |spec|
+          params = params_for(spec, project_id)
+          params[:parent_id] = ids.fetch(spec[:parent]) if spec[:parent]
+          result = client.create_requirement(params)
+
+          unless result[:ok]
+            remaining = ordered.drop(created.length).map { |s| s[:slug] }
+            output.error("Creating '#{spec[:slug]}' failed: #{result[:error]}", status: result[:status])
+            unless output.json?
+              warn "Created #{created.length} of #{ordered.length} before that: #{created.map { |c| c['slug'] }.join(', ')}" unless created.empty?
+              warn "Not created: #{remaining.join(', ')}. Fix the entry and run again with only those."
+            end
+            exit 1
+          end
+
+          requirement = result[:data]['requirement'] || {}
+          ids[spec[:slug]] = requirement['id']
+          created << requirement.merge('parent' => spec[:parent])
+        end
+
+        output.success({ created: created, lint: lint }) do
+          puts "Created #{created.length} requirement(s) from #{opts[:file]} as DRAFTS:"
+          print_batch_table(ordered, lint, created)
+          print_batch_lint(ordered, lint)
+          puts
+          puts '⚠️  These are DRAFTS. A human must activate them in the web app; agents cannot.'
+        end
+      end
+
+      def print_batch_table(ordered, lint, created = nil)
+        status = created&.to_h { |c| [c['slug'], c['status']] }
+        rows = ordered.map do |s|
+          [s[:slug], truncate(s[:title].to_s, 50), s[:parent] || '', s[:required_surfaces].join(','),
+           status ? status[s[:slug]].to_s : 'would create', lint[s[:slug]].length.to_s]
+        end
+        puts
+        output.table(%w[SLUG TITLE PARENT SURFACES STATUS NOTES], rows)
+      end
+
+      def print_batch_lint(ordered, lint)
+        noted = ordered.reject { |s| lint[s[:slug]].empty? }
+        return if noted.empty?
+
+        puts
+        puts 'Wording notes (advice, not errors — a human decides):'
+        noted.each do |s|
+          puts "  #{s[:slug]}:"
+          lint[s[:slug]].each { |n| puts "    - #{n['field']} #{n['message']}" }
+        end
+      end
+
+      # --- Helpers -------------------------------------------------------------------
+
+      def catalog(project_id)
+        result = client.list_requirements(project_id: project_id)
+        unless result[:ok]
+          output.error("Failed to read the project's requirements: #{result[:error]}", status: result[:status])
+          exit 1
+        end
+        result[:data]['requirements'] || []
+      end
+
+      def split_list(raw)
+        return [] if raw.nil?
+
+        raw.split(',').map(&:strip).reject(&:empty?)
+      end
+
+      def blank?(value)
+        value.nil? || value.to_s.strip.empty?
+      end
+
+      # Quality feedback on the draft just created, as part of the same command, so an
+      # agent learns at once that its draft is weak or shouldn't exist and can fix or
+      # withdraw it before a human looks (requirement_analysis_runs_on_draft). It never
+      # undoes the draft: when analysis is unavailable the draft stands and we say so.
+      def draft_feedback(requirement)
+        result = client.analyze_requirement(requirement['id'])
+        return { analysis: result[:data]['analysis'] } if result[:ok] && result[:data].is_a?(Hash) && result[:data]['analysis']
+
+        { error: result[:error] || 'no analysis came back' }
+      end
+
+      def print_feedback(feedback, slug)
+        puts
+        if feedback[:error]
+          puts "Quality feedback could not be produced: #{feedback[:error]}"
+          puts "The draft was still created. Try again later with `fp analyze #{slug}`."
+          return
+        end
+
+        analysis = feedback[:analysis]
+        puts "Quality feedback: #{analysis['verdict'] || 'no verdict'}"
+        Array(analysis['issues']).each do |issue|
+          puts "  - #{issue['type'].to_s.tr('_', ' ')}"
+        end
+        Array(analysis['suggestions']).first(3).each { |suggestion| puts "  → #{suggestion}" }
+        return unless %w[questionable needs_work].include?(analysis['verdict'])
+
+        puts "Revise it with `fp propose-change #{slug} ...`, or withdraw it if it shouldn't be a requirement."
+      end
+
       # Parse a comma-separated --required-types list into a normalized array. Returns []
       # when the flag is absent (meaning "any test counts / inherit project default").
       #

data/lib/fp/commands/propose_change.rb

@@ -23,16 +23,17 @@ module Fp
       help_flag :parent, "Set the parent requirement's slug"
       help_flag :no_parent, 'Propose un-nesting the requirement back to the top level (clears --parent)'
       help_flag :slug, 'Proposed new slug (evidence follows; markers still need updating)'
-      help_flag :reason, 'What prompted this change (use this, not --source-*, to record the prompt)'
+      help_flag :reason, 'What prompted this change, in words (recorded on the change)'
       help_flag :removal, 'Propose deleting the requirement instead of changing it'
       help_flag :withdraw, 'Take back the open proposal you authored, restoring the requirement as it was'
-      help_flag :source_type, "Correct the requirement's recorded origin type (not the change's prompt)"
-      help_flag :source_url, "Correct the requirement's recorded origin URL"
-      help_flag :source_context, "Correct the requirement's recorded origin context"
+      help_flag :source_type, "Where this proposal came from (recorded on the change; the requirement's origin is kept)"
+      help_flag :source_url, 'URL of the card/issue/thread that prompted this proposal'
+      help_flag :source_context, 'Free-form note about what prompted this proposal'
+      help_flag :source_ref, 'A place in the repo that prompted it, e.g. app/models/order.rb:42 (repeatable)'
       help_example 'fp propose-change print_qr --project stowzilla --acceptance "QR scans after 24h at -20C" --reason "Cold-chain rollout"'
       help_example 'fp propose-change print_qr --removal --reason "Superseded by print_container_label"'
-      help_note "Applies the change and drops the requirement to draft for a human to review. Use --reason\n" \
-                "to say what prompted it; --source-* overwrite the requirement's own origin fields."
+      help_note "Applies the change and drops the requirement to draft for a human to review. --reason and\n" \
+                "--source-* record what prompted the proposal in its history; the requirement's own origin is unchanged."
 
       KNOWN_FLAGS = {
         project: :string, name: :string, why: :string, acceptance: :string,
@@ -43,7 +44,7 @@ module Fp
       }.freeze
 
       VALID_CATEGORIES = %w[functional non-functional ux performance security compliance].freeze
-      VALID_SOURCE_TYPES = %w[fizzy discord github_issue jira notion manual ai_chat].freeze
+      VALID_SOURCE_TYPES = %w[fizzy discord github_issue jira notion manual ai_chat repo_scan].freeze
 
       # Flags that describe a proposed new value, mapped to their API field.
       FIELD_FLAGS = {
@@ -55,7 +56,9 @@ module Fp
       }.freeze
 
       def run(args)
+        source_refs, args = extract_repeated(args, '--source-ref')
         opts, positional = parse_flags(args, KNOWN_FLAGS)
+        opts[:source_refs] = source_refs.map(&:strip).reject(&:empty?)
         require_project!(opts)
 
         slug = positional.first
@@ -82,6 +85,7 @@ module Fp
           exit 1
         end
 
+        warn_if_not_production!
         result = client.propose_requirement_change(requirement['id'], params)
         unless result[:ok]
           if result[:status] == 409 && result[:details].is_a?(Hash)
@@ -220,6 +224,7 @@ module Fp
         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[:source_refs] = opts[:source_refs] unless opts[:source_refs].nil? || opts[:source_refs].empty?
 
         params
       end
@@ -290,6 +295,7 @@ module Fp
         puts "  Source:  #{source['type']}" if source['type']
         puts "  URL:     #{source['url']}" if source['url']
         puts "  Context: #{source['context']}" if source['context']
+        Array(source['refs']).each { |ref| puts "  Ref:     #{ref}" }
         puts
       end