featureparity 0.0.14 → 0.0.16

data/lib/fp/commands/init.rb

@@ -213,6 +213,9 @@ module Fp
             gate:
               name: Parity gate
               runs-on: ubuntu-latest
+              permissions:
+                contents: read
+                pull-requests: write
               steps:
                 - uses: actions/checkout@v4
 
@@ -223,6 +226,21 @@ module Fp
                 - name: Install fp
                   run: gem install featureparity
 
+                - name: Update PR requirement changes
+                  if: github.event_name == 'pull_request'
+                  env:
+                    FP_API_KEY: ${{ secrets.FP_API_KEY }}
+                    GITHUB_TOKEN: ${{ github.token }}
+                  run: |
+                    if fp help | grep -q -- '--github-pr'; then
+                      fp changes --github-pr --github-summary
+                    else
+                      echo '## FeatureParity requirement changes' >> "$GITHUB_STEP_SUMMARY"
+                      echo '' >> "$GITHUB_STEP_SUMMARY"
+                      echo 'The installed fp version cannot update the pull request description yet.' >> "$GITHUB_STEP_SUMMARY"
+                      exit 1
+                    fi
+
                 # Exits non-zero when the project violates its enforcement level.
                 # Add `--warn-only` while adopting if you need the annotations without
                 # blocking merges yet.
@@ -290,22 +308,61 @@ module Fp
              If one is wrong or outdated, propose the change — never edit or ignore it.
 
           **Start every task by checking the requirements — before you write code, not
-          after.** When you pick up a feature or bug, first run `fp list` / `fp show` to find
-          the requirement it belongs to. If one exists, you'll bind your test to it; if none
-          does, propose one (as a draft) so the work is on the record from the outset. Treating
-          this as the opening move — not a chore at the end — is what keeps parity honest.
+          after.** When you pick up a feature or bug, first inventory the full request and
+          compare it with the active and draft requirements. Find what already covers the work,
+          what must change, and what is missing. Treating this as the opening move — not a chore
+          at the end — is what keeps the catalog trustworthy.
 
-          ### 1. Find the requirement — do this first
+          ### 1. Find and model the requirements — do this first
 
           ```bash
           fp list                      # active requirements (project comes from .featureparity.yml)
+          fp list --status draft       # proposed work — check before creating duplicates
           fp list --gaps               # the ones with no evidence yet — good places to start
           fp show <slug>               # details, acceptance criteria, and existing receipts
           fp history <slug>            # why it says what it says, and whether a change is pending
+          fp changes --source-url URL   # requirement activity prompted by a work item
           ```
 
-          If no requirement covers what you're building, propose one. Agents always create
-          **drafts**; a human activates them:
+          **The requirement catalog is the human-readable product specification, not a box to
+          tick with one umbrella record.** It records the team's current shared understanding;
+          it is not a finished decree handed from product to engineering. Refine requirements
+          through ongoing conversation with customers, domain experts, and builders. The human
+          product owner decides value and priority; agents should surface gaps, inconsistencies,
+          alternatives, and useful splits rather than silently making product decisions.
+
+          Before coding, enumerate the independently meaningful promises in the request:
+          user-visible behaviours, policies, limits, plans, deadlines, state transitions,
+          permissions, failure modes, and affected surfaces. Then model them:
+
+          - Give each independently testable or independently failable product promise its own
+            focused requirement. If one acceptance sentence joins behaviours that could pass or
+            fail separately, split it.
+          - Use a parent for the broad capability and children for distinct behaviours, policies,
+            or surface-specific promises. Do not create requirements for implementation details
+            or refactors that make no product promise.
+          - Put concrete product decisions — prices, quotas, dates, roles, fallbacks — in the
+            requirement acceptance criteria. Never leave them only as assumptions in code or a PR.
+          - Check adjacent requirements and their history. New requirements do not excuse an old
+            requirement that the work makes inaccurate; propose a change to keep the whole catalog true.
+          - Before finishing, reconcile the implementation against the catalog: every shipped
+            behaviour maps to a current requirement, every changed promise is recorded, and every
+            focused requirement has appropriate marked evidence or an explicit gap. A broad marker
+            must never appear to prove several acceptance clauses that its test does not exercise.
+
+          **Prevent contradictions before they enter the catalog.** Before proposing a new or changed
+          promise, compare its intended acceptance criteria with related active and draft requirements
+          and read their history. Ask whether both promises can be true at the same time for the same
+          user, state, and conditions. If not, do not add another requirement.
+
+          A failing test bound to an existing requirement, or an implementation that only works by
+          changing one, is a contradiction signal — not permission to weaken the test or write a
+          second requirement around it. Identify which promise matches product intent, then use
+          `fp propose-change` (or `--removal`) with the source and reason to put that decision before
+          a human. If the intent is unclear, stop and ask rather than making the catalog say both things.
+
+          If no requirement covers what you're building, propose one or a parent/child tree. Agents
+          always create **drafts**; a human activates them:
 
           ```bash
           fp propose --slug <slug> --name "..." --required <surface>,<surface> \\
@@ -313,18 +370,45 @@ module Fp
             --source-type fizzy --source-url <card-or-issue-url>
           ```
 
-          **Writing the `--why`: brief, and it actually explains why.** Someone approving
-          this requirement needs to grasp in one read why the product needs it — the user
-          problem it solves or the outcome it protects. State that and stop. Longer is fine
-          when it earns its length; wordy is not. Avoid two things: filler that says nothing
-          specific, and describing *how* the feature works instead of *why* anyone wants it.
-
-          - ✅ `--why "Warehouse staff scan the label to look up a container; without a QR code they key in the ID by hand and mis-type it."`
-          - ❌ `--why "This is an important requirement that ensures a high-quality experience for our users across all surfaces."` (filler — says nothing specific)
-          - ❌ `--why "The label renders a QR image encoding the container ID at print time."` (how it works, not why anyone needs it)
-
-          Same rule for `--acceptance`: state the observable condition that proves it's done
-          (`"QR scans to the container's detail page"`), not a restatement of the title.
+          **Write a requirement as a product decision someone can approve, not as a design
+          task.** It should read like a capable teammate wrote it: direct, specific, and free
+          of boilerplate such as “ensure a seamless experience.”
+
+          - **Title:** one clear product promise in present tense. Name the user-visible
+            capability, not the work (`“Dispatchers see current shipment status”`, not
+            `“Implement status polling”`).
+          - **Why:** one or two natural sentences naming who needs this, the problem or risk,
+            and the outcome worth protecting. Do not repeat the title, sell the feature, or
+            explain the mechanism.
+          - **Acceptance:** the observable behaviour that would let a reviewer decide whether
+            the promise is true. State the trigger or situation, the result, and material
+            boundaries such as permissions, failure states, and affected surfaces. Use examples
+            and marked tests to ground and double-check the rule. Do not mistake a few examples for the rule
+            or let tests stand for every case; neither replaces the general rule and continued
+            conversation.
+          - **Numbers and policy:** include a price, limit, timeout, date, role, or fallback only
+            when the source made it a real product decision. Never invent a plausible value to
+            fill a gap. If the decision matters and the source is silent, ask.
+          - **Implementation detail:** leave out components, data models, algorithms, endpoints,
+            and UI controls unless that interface or constraint is itself part of the promise.
+
+          Learn from the request, existing requirements and history, and available evidence about
+          what users actually do. Look for what they attempt, where they abandon a task, what they
+          use, and what experiments reveal. Treat the first proposed solution as input, not
+          unquestionable scope. Preserve important uncertainty as a question rather than
+          laundering a guess into acceptance criteria.
+
+          - ✅ **Title:** `Dispatchers see current shipment status`
+            **Why:** `Dispatchers need to spot delayed shipments before they miss a delivery window.`
+            **Acceptance:** `When a shipment's status changes, the dashboard shows the new status; if status is unavailable, it says so instead of presenting stale data as current.`
+          - ❌ **Title:** `Implement Redis-backed 30-second status polling`
+            **Why:** `This important feature ensures a seamless, robust experience.`
+            **Acceptance:** `Use a background worker and refresh every 30 seconds.`
+            This invents policy, prescribes a design, and never states the product outcome.
+
+          Before proposing, read the draft once as a manager deciding scope: is the value clear,
+          can the result be observed, are product decisions distinguished from guesses, and can
+          every sentence earn its place? If not, revise or ask before writing the record.
 
           ### 2. If the requirement is wrong, propose a change — don't silently edit it
 
@@ -347,8 +431,9 @@ module Fp
 
           - Never edit a requirement's wording by any other route. `fp propose-change` is the
             only one that records what it was and what prompted the change.
-          - You cannot change `--slug` (it's the join to every `fp:<slug>` marker) or remove a
-            required surface. Both come back as 403.
+          - You may correct `--name` (the title) or `--slug` through a proposal. Existing evidence
+            follows a proposed slug, but every `fp:<slug>` marker still needs the same correction.
+            You still cannot remove a required surface.
           - You cannot approve or reject — not even your own proposal.
           - One open proposal per requirement (409 otherwise). Run `fp history <slug>` first.
           - **A requirement awaiting review still counts toward the gate.** Proposing a change

data/lib/fp/commands/propose.rb

@@ -2,7 +2,7 @@
 
 module Fp
   module Commands
-    # fp propose --project <slug> --slug X --name "..." --why "..." --required a,b,c --acceptance "..." --parent <slug> --category <cat>
+    # 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
     class Propose < Base
       KNOWN_FLAGS = {
@@ -11,6 +11,7 @@ module Fp
         name: :string,
         why: :string,
         required: :string,
+        required_types: :string,
         acceptance: :string,
         parent: :string,
         category: :string,
@@ -27,7 +28,7 @@ module Fp
         opts, = parse_flags(args, KNOWN_FLAGS)
 
         require_project!(opts)
-        require_flag(opts, :slug, '--slug is required (immutable identifier for the requirement)')
+        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)
@@ -41,6 +42,9 @@ module Fp
           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])
 
         # Parse required surfaces (comma-separated)
@@ -56,6 +60,7 @@ module Fp
           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]
@@ -94,6 +99,9 @@ module Fp
           puts "  Category: #{requirement['category'] || '(none)'}"
           puts "  Tags:     #{(requirement['tags'] || []).join(', ')}" unless (requirement['tags'] || []).empty?
           puts "  Surfaces: #{(requirement['required_surfaces'] || []).join(', ')}"
+          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
           puts '⚠️  This requirement is a DRAFT.'
@@ -104,6 +112,19 @@ module Fp
 
       private
 
+      # Parse a comma-separated --required-types list into a normalized array. Returns []
+      # when the flag is absent (meaning "any test counts / inherit project default").
+      #
+      # No client-side enum check: valid test types are the *project's* vocabulary
+      # (Project#test_type_vocabulary), which the CLI doesn't know without a round-trip.
+      # The server validates against that list and returns a verbatim 422 the caller
+      # sees — the same way an unknown surface is handled.
+      def parse_test_types(raw)
+        return [] if raw.nil? || raw.to_s.strip.empty?
+
+        raw.split(',').map { |t| t.strip.downcase }.reject(&:empty?).uniq
+      end
+
       # Resolve a parent requirement slug to its ID
       def resolve_parent_id(project_id, parent_slug)
         result = client.list_requirements(project_id: project_id)

data/lib/fp/commands/propose_change.rb

@@ -12,7 +12,7 @@ module Fp
     class ProposeChange < Base
       KNOWN_FLAGS = {
         project: :string, name: :string, why: :string, acceptance: :string,
-        required: :string, category: :string, parent: :string, slug: :string,
+        required: :string, required_types: :string, category: :string, parent: :string, slug: :string,
         reason: :string, source_type: :string, source_url: :string, source_context: :string,
         removal: :boolean
       }.freeze
@@ -48,8 +48,8 @@ module Fp
         removal = opts[:removal] ? true : false
 
         if !removal && params.keys.none? { |k| proposed_field?(k) }
-          output.error('Nothing to propose. Pass at least one of --name/--why/--acceptance/' \
-                       '--required/--category/--parent, or --removal to propose deletion.')
+          output.error('Nothing to propose. Pass at least one of --name/--slug/--why/--acceptance/' \
+                       '--required/--required-types/--category/--parent, or --removal to propose deletion.')
           exit 1
         end
 
@@ -70,6 +70,10 @@ module Fp
           exit 1
         end
 
+        # No client-side test-type check: the valid set is the project's own vocabulary
+        # (Project#test_type_vocabulary), which the CLI can't know without a round-trip.
+        # The server validates and returns a verbatim 422.
+
         return unless opts[:source_type] && !VALID_SOURCE_TYPES.include?(opts[:source_type])
 
         output.error("Invalid source type '#{opts[:source_type]}'. Must be one of: #{VALID_SOURCE_TYPES.join(', ')}")
@@ -90,6 +94,9 @@ module Fp
 
         FIELD_FLAGS.each { |flag, field| params[field] = opts[flag] if opts[flag] }
         params[:required_surfaces] = opts[:required].split(',').map(&:strip) if opts[:required]
+        if opts[:required_types]
+          params[:required_test_types] = opts[:required_types].split(',').map { |t| t.strip.downcase }.reject(&:empty?)
+        end
         params[:parent_id] = resolve_parent_id(project_id, opts[:parent]) if opts[:parent]
 
         params[:removal] = true if opts[:removal]
@@ -102,7 +109,7 @@ module Fp
       end
 
       def proposed_field?(key)
-        %i[title why acceptance category slug required_surfaces parent_id].include?(key)
+        %i[title why acceptance category slug required_surfaces required_test_types parent_id].include?(key)
       end
 
       def resolve_parent_id(project_id, parent_slug)
@@ -136,11 +143,12 @@ module Fp
           print_diff(change['changes'])
           print_source(change)
 
+          current_slug = requirement['slug'].to_s.empty? ? slug : requirement['slug']
           puts "  Status:   #{requirement['status']}"
           puts "  Change:   #{change['id']}"
           puts
           puts '⚠️  This requirement is back in DRAFT pending human review.'
-          puts "   Run `fp history #{slug} --project <project>` to see the full diff."
+          puts "   Run `fp history #{current_slug} --project <project>` to see the full diff."
           puts '   A human must approve or reject it in the web app. Agents cannot review changes.'
         end
       end

data/lib/fp/commands/report.rb

@@ -18,6 +18,7 @@ module Fp
       KNOWN_FLAGS = {
         project: :string,
         surface: :string,
+        test_type: :string,
         file: :string,
         line: :string,
         repo: :string,
@@ -57,6 +58,10 @@ module Fp
           exit 1
         end
 
+        # No client-side test-type check: the valid set is the project's own vocabulary,
+        # which the CLI can't know without a round-trip. The server validates and returns
+        # a verbatim 422.
+
         project_id = resolve_project_id(opts[:project])
 
         # Verify the requirement exists before reporting evidence
@@ -75,6 +80,7 @@ module Fp
           repo: opts[:repo],
           state: state
         }
+        params[:test_type] = opts[:test_type] if opts[:test_type]
         params[:pr_url] = opts[:pr] if opts[:pr]
         params[:sha] = opts[:sha] if opts[:sha]
         params[:work_item_url] = opts[:work_item] if opts[:work_item]
@@ -112,6 +118,7 @@ module Fp
         output.success(result[:data]) do
           puts "Evidence reported for '#{slug}' on surface '#{opts[:surface]}'."
           puts "  State: #{state}"
+          puts "  Type:  #{opts[:test_type]}" if opts[:test_type]
           puts "  File:  #{opts[:file]}#{opts[:line] ? ":#{opts[:line]}" : ''}"
           if opts[:pr]
             puts "  PR:    #{opts[:pr]}"
@@ -150,6 +157,9 @@ module Fp
           exit 1
         end
 
+        # No client-side test-type check — the server validates --test-type / marker
+        # types against the project's own vocabulary and returns a verbatim 422.
+
         begin
           testcases = Fp::JUnit.parse_file(opts[:junit])
         rescue ArgumentError => e
@@ -163,7 +173,11 @@ module Fp
         end
 
         base_dir = opts[:base_dir] || Dir.pwd
-        result = Fp::JUnit.bind_markers(testcases, base_dir: base_dir, default_surface: opts[:surface])
+        # --test-type is the default kind for markers that pin none (`fp:slug`,
+        # `fp:slug@api`); a marker's own `:type` suffix always wins.
+        result = Fp::JUnit.bind_markers(testcases, base_dir: base_dir,
+                                        default_surface: opts[:surface],
+                                        default_test_type: opts[:test_type])
         bindings = result[:bindings]
         unmatched = result[:unmatched]
         missing_surface = result[:missing_surface] || []
@@ -207,6 +221,7 @@ module Fp
             repo: opts[:repo],
             state: state
           }
+          params[:test_type] = binding.test_type if binding.test_type
           params[:line] = binding.line if binding.line
           params[:pr_url] = opts[:pr] if opts[:pr]
           params[:sha] = opts[:sha] if opts[:sha]
@@ -238,7 +253,7 @@ module Fp
       def emit_junit_summary(opts, reported, skipped_unknown, unmatched, api_unavailable)
         data = {
           repo: opts[:repo],
-          reported: reported.map { |r| { slug: r[:binding].slug, surface: r[:binding].surface, file: r[:binding].file, line: r[:binding].line, state: r[:state], recorded: r[:recorded] } },
+          reported: reported.map { |r| { slug: r[:binding].slug, surface: r[:binding].surface, test_type: r[:binding].test_type, file: r[:binding].file, line: r[:binding].line, state: r[:state], recorded: r[:recorded] } },
           skipped_unknown: skipped_unknown.map { |b| { slug: b.slug, surface: b.surface, file: b.file } },
           unmatched_testcases: unmatched.map { |tc| { name: tc.name, file: tc.file } }
         }
@@ -248,7 +263,8 @@ module Fp
           reported.each do |r|
             marker = r[:recorded] ? '✓' : '•'
             loc = r[:binding].line ? "#{r[:binding].file}:#{r[:binding].line}" : r[:binding].file
-            puts "  #{marker} #{r[:binding].slug} → #{r[:binding].surface}  (#{r[:state]})  #{loc}"
+            type = r[:binding].test_type ? " [#{r[:binding].test_type}]" : ''
+            puts "  #{marker} #{r[:binding].slug} → #{r[:binding].surface}#{type}  (#{r[:state]})  #{loc}"
           end
 
           unless skipped_unknown.empty?

data/lib/fp/commands/show.rb

@@ -24,6 +24,7 @@ module Fp
         end
 
         requirement = result[:data]['requirement']
+        source_history = result[:data]['source_history'] || []
 
         # Evidence is not embedded in the requirement payload — it lives on the project's
         # evidence collection, keyed by slug. Fetch it, or `fp show` reports "(none)" for
@@ -37,7 +38,7 @@ module Fp
         payload['parent_slug'] = parent_slug if parent_slug
 
         output.success(payload) do
-          print_requirement(requirement, evidence: evidence, parent_slug: parent_slug)
+          print_requirement(requirement, evidence: evidence, parent_slug: parent_slug, source_history: source_history)
         end
       end
 
@@ -60,7 +61,7 @@ module Fp
         parent && parent['slug']
       end
 
-      def print_requirement(req, evidence: [], parent_slug: nil)
+      def print_requirement(req, evidence: [], parent_slug: nil, source_history: [])
         puts "#{req['title']}"
         puts "=" * req['title'].length
         puts
@@ -81,6 +82,19 @@ module Fp
         end
         puts
 
+        # Required test types: the kinds of test that must each cover this requirement on
+        # every surface. Empty means "any test counts" (or it inherits the project
+        # default) — shown explicitly so an agent knows whether one test is enough.
+        test_types = req['required_test_types'] || []
+        puts 'Required Test Types:'
+        if test_types.empty?
+          puts '  (any — a single test of any kind satisfies each surface)'
+        else
+          test_types.each { |t| puts "  - #{t}" }
+          puts '  (each kind needs its own evidence on every required surface)'
+        end
+        puts
+
         if req['why'] && !req['why'].empty?
           puts 'Why:'
           puts "  #{req['why']}"
@@ -93,6 +107,23 @@ module Fp
           puts
         end
 
+        # Source trail: every source (Fizzy card, Discord thread, issue) that prompted a
+        # change to this requirement, oldest first. Derived from events so the history is
+        # additive — older sources aren't lost when a new one is recorded.
+        puts 'Source Trail:'
+        if source_history.empty?
+          puts '  (no sources recorded)'
+        else
+          source_history.each do |src|
+            line = []
+            line << src['type'] if src['type']
+            line << src['url'] if src['url']
+            puts "  - #{line.join(' ')}"
+            puts "    #{src['context']}" if src['context']
+          end
+        end
+        puts
+
         # Evidence receipts, newest first, grouped per surface.
         puts 'Evidence:'
         if evidence.empty?
@@ -107,6 +138,7 @@ module Fp
               puts "  #{surface}:"
               records.each do |e|
                 puts "    Status:  #{e['status']}"
+                puts "    Type:    #{e['test_type']}" if e['test_type'] && e['test_type'] != 'unspecified'
                 if e['source_file']
                   loc = e['source_line'] ? "#{e['source_file']}:#{e['source_line']}" : e['source_file']
                   puts "    File:    #{loc}"

data/lib/fp/commands.rb

@@ -8,6 +8,7 @@ require_relative 'commands/show'
 require_relative 'commands/propose'
 require_relative 'commands/propose_change'
 require_relative 'commands/history'
+require_relative 'commands/changes'
 require_relative 'commands/report'
 require_relative 'commands/ci_report'
 require_relative 'commands/check'
@@ -21,6 +22,9 @@ require_relative 'commands/setup'
 require_relative 'commands/whoami'
 require_relative 'commands/version'
 require_relative 'commands/help'
+require_relative 'commands/attach'
+require_relative 'commands/attachments'
+require_relative 'commands/conversation'
 
 module Fp
   module Commands