featureparity 0.0.15 → 0.0.16

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: efbe901394a8f97be6d1340a877ecafa6a8151453ed5a78708e91b6e40af1fe1
-  data.tar.gz: 51358f9c7907107f3744775e414f175a1206ace2a104b44dcfcee4723a13e8e4
+  metadata.gz: dd15c5892d88c0202433fd6e11993440f45cd3cb8c754c0c7138309008190cbb
+  data.tar.gz: 356c8c54af360a47639e2dfc6313774247ff93534eb02b6666656f738d69ce70
 SHA512:
-  metadata.gz: 16067e82a07cac5e0bf5df3548950ff5d966e8f822ba6315740f474a9d50e17fa25f99adfc9fc4a58a2af66bcd03f3e0edce7e9ab143e05fb6f4b9c2fe2e013e
-  data.tar.gz: 8f58e25f9465851931d0d763f1655b56112cd7899e919af8ee5bf0975fc6ec090c631fc42d993f76dce210468ce4d766cea2c1575b62282f35a969f2124e7530
+  metadata.gz: d0d96204c4cf14ff9c7f5bbf1930f1ad6f170b11be67651df1cda342c2ad41e53e1a09ea93bed84db620d2c867f26ffbc313fa2d132f7b5b8b474026b4ea9ee8
+  data.tar.gz: c43e169274e9c6484b6e41c2bcb1c5748eaee9dabad8c39f523c7ed30a08f0edaeae3df7637edc799d2089165624108e72fdb517c95d580cc51c1b747064726b

data/lib/fp/cli.rb

@@ -12,6 +12,7 @@ module Fp
       'propose' => Commands::Propose,
       'propose-change' => Commands::ProposeChange,
       'history' => Commands::History,
+      'changes' => Commands::Changes,
       'report' => Commands::Report,
       'ci-report' => Commands::CiReport,
       'check' => Commands::Check,

data/lib/fp/client.rb

@@ -98,6 +98,14 @@ module Fp
       put("/api/requirements/#{id}", params)
     end
 
+    # GET /projects/:project_id/requirement_changes — project-wide audit activity,
+    # optionally narrowed to the exact work-item URL that prompted it.
+    def list_project_requirement_changes(project_id, source_url: nil)
+      params = {}
+      params[:source_url] = source_url if source_url
+      get("/api/projects/#{project_id}/requirement_changes", params)
+    end
+
     # GET /requirements/:id/changes
     #
     # A requirement's change history: what it was, what changed, who changed it, and

data/lib/fp/commands/changes.rb

@@ -0,0 +1,359 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'net/http'
+require 'openssl'
+require 'uri'
+
+module Fp
+  module Commands
+    # `fp changes` lists requirement activity associated with a work item. In GitHub
+    # Actions it can discover source URLs from the pull request body, append a job
+    # summary, and keep a managed table in the pull request description itself.
+    class Changes < Base
+      PR_SECTION_BEGIN = '<!-- feature-parity:requirement-changes:begin -->'
+      PR_SECTION_END = '<!-- feature-parity:requirement-changes:end -->'
+
+      KNOWN_FLAGS = {
+        project: :string,
+        source_url: :string,
+        github_summary: :boolean,
+        github_pr: :boolean
+      }.freeze
+
+      TYPE_LABELS = {
+        'created' => 'Created',
+        'updated' => 'Edited',
+        'activated' => 'Activated',
+        'archived' => 'Archived',
+        'rejected' => 'Rejected',
+        'destroyed' => 'Deleted',
+        'change_proposed' => 'Modification proposed',
+        'removal_proposed' => 'Removal proposed',
+        'change_approved' => 'Change approved',
+        'change_rejected' => 'Change rejected'
+      }.freeze
+
+      def run(args)
+        explicit_urls, rest = extract_repeated(args, '--source-url')
+        opts, = parse_flags(rest, KNOWN_FLAGS)
+        project_config = ProjectConfig.discover
+        project_slug = require_project!(opts, project_config)
+        @github_pull_request = fetch_github_pull_request if opts[:github_pr]
+
+        source_urls = explicit_urls.map(&:strip).reject(&:empty?).uniq
+        source_urls = github_source_urls if source_urls.empty?
+
+        data = {
+          project: project_slug,
+          source_urls: source_urls,
+          requirement_changes: [],
+          source_detected: !source_urls.empty?
+        }
+
+        if source_urls.any?
+          project_id = resolve_project_id(project_slug)
+          data[:requirement_changes] = fetch_changes(project_id, source_urls)
+        end
+
+        markdown = render_markdown(data)
+        destinations = []
+
+        if opts[:github_summary]
+          append_github_summary(markdown)
+          destinations << ENV['GITHUB_STEP_SUMMARY']
+        end
+        if opts[:github_pr]
+          update_github_pull_request(markdown)
+          destinations << 'the pull request description'
+        end
+
+        output.success(data) do
+          if destinations.any?
+            puts "FeatureParity requirement-change table updated in #{destinations.join(' and ')}."
+          else
+            puts markdown
+          end
+        end
+      end
+
+      private
+
+      def fetch_changes(project_id, source_urls)
+        changes = []
+
+        source_urls.each do |source_url|
+          result = client.list_project_requirement_changes(project_id, source_url: source_url)
+          if [400, 403, 404].include?(result[:status].to_i) && result[:error].to_s.match?(/bad request|not found/i)
+            return legacy_changes(project_id, source_urls)
+          end
+
+          unless result[:ok]
+            output.error(result[:error], status: result[:status])
+            exit 1
+          end
+
+          changes.concat(result[:data]['requirement_changes'] || [])
+        end
+
+        collapse_to_latest_per_requirement(
+          changes.uniq { |change| change['id'] }
+                 .sort_by { |change| change['recorded_at'].to_s }
+                 .reverse
+        )
+      end
+
+      # Option A: one row per requirement. A requirement whose creation and a later
+      # modification proposal both trace to the same work item would otherwise appear
+      # twice, which reads as a duplicate. We keep only the most recent event per
+      # requirement, so the table answers "where does each requirement stand now?"
+      # rather than replaying its whole timeline (that lives in `fp history <slug>`).
+      def collapse_to_latest_per_requirement(changes)
+        changes.each_with_object({}) do |change, latest|
+          key = change['slug'] || change['requirement_path'] || change['id']
+          latest[key] ||= change
+        end.values
+      end
+
+      # Compatibility with an API that predates the project activity endpoint. This is
+      # especially useful while a CLI/API release is rolling out: requirements whose own
+      # source matches the work item, plus every open proposal, are inspected through the
+      # existing per-requirement history endpoint. Once the endpoint is deployed, its
+      # ProjectIndex also covers reviewed and deleted activity without this bounded scan.
+      def legacy_changes(project_id, source_urls)
+        result = client.list_requirements(project_id: project_id)
+        unless result[:ok]
+          output.error(result[:error], status: result[:status])
+          exit 1
+        end
+
+        requirements = result[:data]['requirements'] || []
+        candidates = requirements.select do |requirement|
+          source_urls.include?(requirement['source_url']) || present?(requirement['pending_change_id'])
+        end
+
+        collapsed = candidates.flat_map do |requirement|
+          history = client.list_requirement_changes(requirement['id'])
+          next [] unless history[:ok]
+
+          (history[:data]['changes'] || []).filter_map do |change|
+            next unless source_urls.include?(change.dig('source', 'url'))
+
+            change.merge(
+              'slug' => requirement['slug'],
+              'title' => requirement['title'],
+              'requirement_status' => requirement['status'],
+              'requirement_path' => "/projects/#{project_id}/requirements/#{requirement['id']}",
+              'review_state' => change.dig('review', 'decision') || (change['pending'] ? 'pending' : requirement['status'])
+            )
+          end
+        end.uniq { |change| change['id'] }
+           .sort_by { |change| change['recorded_at'].to_s }
+           .reverse
+
+        collapse_to_latest_per_requirement(collapsed)
+      end
+
+      def github_source_urls
+        body = if @github_pull_request
+                 @github_pull_request.fetch('body', '').to_s
+               else
+                 github_event.dig('pull_request', 'body').to_s
+               end
+
+        body = body.sub(/#{Regexp.escape(PR_SECTION_BEGIN)}.*?#{Regexp.escape(PR_SECTION_END)}/m, '')
+
+        # Option B: explicit fp-source markers take precedence
+        explicit = body.scan(/fp-source:\s*(https?:\/\/\S+)/i).flatten.map { |url| clean_url(url) }
+        return explicit.uniq if explicit.any?
+
+        # Option A: heuristic detection of ticket-tracker URLs
+        URI.extract(body, %w[http https])
+           .map { |url| clean_url(url) }
+           .select { |url| work_item_url?(url) }
+           .uniq
+      end
+
+      def github_event
+        return @github_event if defined?(@github_event)
+
+        event_path = ENV['GITHUB_EVENT_PATH']
+        @github_event = if present?(event_path) && File.file?(event_path)
+                          JSON.parse(File.read(event_path))
+                        else
+                          {}
+                        end
+      rescue JSON::ParserError
+        @github_event = {}
+      end
+
+      def work_item_url?(url)
+        # Heuristic detection: accept URLs that look like ticket trackers.
+        # Matches paths containing common ticket-tracker segments.
+        url.match?(%r{
+          \Ahttps?://[^/]+           # scheme and host
+          (?:
+            .*/(?:issues|cards|browse|tickets|tasks|work[-_]?items?|bugs?|stories?|features?|pull|merge_requests?|issue|story|_workitems|channels|c|t)/[^\s/]+ |
+            .*/\d+(?:/|\z)           # any path ending in /123 or /123/
+          )
+        }xi)
+      end
+
+      def clean_url(url)
+        url.sub(/[)\]}>.,;:]+\z/, '')
+      end
+
+      def append_github_summary(markdown)
+        path = ENV['GITHUB_STEP_SUMMARY']
+        unless present?(path)
+          output.error('--github-summary requires GITHUB_STEP_SUMMARY (it is set automatically by GitHub Actions)')
+          exit 1
+        end
+
+        File.open(path, 'a') { |file| file.puts(markdown) }
+      end
+
+      def fetch_github_pull_request
+        token, uri = github_credentials
+        response = github_request(Net::HTTP::Get, uri, token)
+        fail_github_request!('read the pull request', response) unless response.is_a?(Net::HTTPSuccess)
+
+        JSON.parse(response.body)
+      rescue JSON::ParserError
+        output.error('GitHub returned an invalid response while reading the pull request')
+        exit 1
+      rescue SystemCallError, SocketError, Timeout::Error, OpenSSL::SSL::SSLError => e
+        output.error("Could not read the pull request from GitHub: #{e.message}")
+        exit 1
+      end
+
+      def update_github_pull_request(markdown)
+        current_body = @github_pull_request.fetch('body', '').to_s
+        updated_body = managed_pull_request_body(current_body, markdown)
+        return if updated_body == current_body
+
+        token, uri = github_credentials
+        response = github_request(Net::HTTP::Patch, uri, token, body: { body: updated_body })
+        fail_github_request!('update the pull request description', response) unless response.is_a?(Net::HTTPSuccess)
+      rescue SystemCallError, SocketError, Timeout::Error, OpenSSL::SSL::SSLError => e
+        output.error("Could not update the pull request description on GitHub: #{e.message}")
+        exit 1
+      end
+
+      def managed_pull_request_body(body, markdown)
+        section = "#{PR_SECTION_BEGIN}\n#{markdown}\n#{PR_SECTION_END}"
+        begin_count = body.scan(PR_SECTION_BEGIN).length
+        end_count = body.scan(PR_SECTION_END).length
+
+        unless [begin_count, end_count].all? { |count| [0, 1].include?(count) } && begin_count == end_count
+          output.error('The pull request description has malformed or duplicate FeatureParity requirement-change markers')
+          exit 1
+        end
+
+        if begin_count == 1
+          body.sub(/#{Regexp.escape(PR_SECTION_BEGIN)}.*?#{Regexp.escape(PR_SECTION_END)}/m, section)
+        else
+          [body.rstrip, section].reject(&:empty?).join("\n\n") + "\n"
+        end
+      end
+
+      def github_credentials
+        token = ENV['GITHUB_TOKEN']
+        repository = ENV['GITHUB_REPOSITORY'].to_s
+        number = github_event.dig('pull_request', 'number') || github_event['number']
+
+        unless present?(token) && repository.match?(%r{\A[^/]+/[^/]+\z}) && number.to_i.positive?
+          output.error('--github-pr requires GITHUB_TOKEN, GITHUB_REPOSITORY, and a pull_request GITHUB_EVENT_PATH')
+          exit 1
+        end
+
+        owner, repo = repository.split('/', 2).map { |part| URI.encode_www_form_component(part) }
+        api_url = ENV.fetch('GITHUB_API_URL', 'https://api.github.com').sub(%r{/+\z}, '')
+        [token, URI.parse("#{api_url}/repos/#{owner}/#{repo}/pulls/#{number.to_i}")]
+      rescue URI::InvalidURIError
+        output.error('GITHUB_API_URL is not a valid URL')
+        exit 1
+      end
+
+      def github_request(request_class, uri, token, body: nil)
+        request = request_class.new(uri)
+        request['Accept'] = 'application/vnd.github+json'
+        request['Authorization'] = "Bearer #{token}"
+        request['User-Agent'] = 'featureparity-cli'
+        request['X-GitHub-Api-Version'] = '2022-11-28'
+        if body
+          request['Content-Type'] = 'application/json'
+          request.body = JSON.generate(body)
+        end
+
+        Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == 'https') do |http|
+          http.request(request)
+        end
+      end
+
+      def fail_github_request!(action, response)
+        details = JSON.parse(response.body).fetch('message', response.body.to_s)
+        output.error("GitHub could not #{action}: #{details}", status: response.code.to_i)
+        exit 1
+      rescue JSON::ParserError
+        output.error("GitHub could not #{action}: HTTP #{response.code}", status: response.code.to_i)
+        exit 1
+      end
+
+      def render_markdown(data)
+        lines = ['## FeatureParity requirement changes', '']
+
+        unless data[:source_detected]
+          lines << '⚠️ No work-item URL was found in the pull request description, so FeatureParity cannot determine which requirement activity belongs to this change.'
+          return lines.join("\n")
+        end
+
+        links = data[:source_urls].map { |url| "[#{markdown_escape(url)}](#{url})" }
+        lines << "Work item#{links.length == 1 ? '' : 's'}: #{links.join(', ')}"
+        lines << ''
+
+        changes = data[:requirement_changes]
+        if changes.empty?
+          lines << 'No requirement changes are recorded for the linked work item(s).'
+          return lines.join("\n")
+        end
+
+        lines << '| Requirement | Change | Review | Actor |'
+        lines << '| --- | --- | --- | --- |'
+        changes.each do |change|
+          lines << "| #{requirement_cell(change)} | #{TYPE_LABELS.fetch(change['type'], change['type'])} | " \
+                   "#{markdown_escape(change['review_state'] || change['requirement_status'] || '—')} | " \
+                   "#{markdown_escape(change['actor'] || '—')} |"
+        end
+        lines << ''
+        lines << '_Open the linked requirement to review its wording, diff, evidence, and decision state._'
+        lines.join("\n")
+      end
+
+      def requirement_cell(change)
+        slug = change['slug'] || 'unknown'
+        title = markdown_escape(change['title'] || slug)
+        path = change['requirement_path']
+        return title unless present?(path)
+
+        "[#{title}](#{web_base_url}#{path})"
+      end
+
+      def web_base_url
+        uri = URI.parse(config.api_url)
+        host = uri.host.to_s.sub(/\Aapi\./, '')
+        "#{uri.scheme || 'https'}://#{host}"
+      rescue URI::InvalidURIError
+        'https://featureparity.dev'
+      end
+
+      def markdown_escape(value)
+        value.to_s.gsub('|', '\\|').gsub("\n", ' ')
+      end
+
+      def present?(value)
+        !value.nil? && !value.to_s.strip.empty?
+      end
+    end
+  end
+end

data/lib/fp/commands/help.rb

@@ -23,6 +23,7 @@ module Fp
             propose-change <slug> ...         Propose a change to an existing requirement
             propose-change <slug> --removal   Propose deleting a requirement
             history <slug> --project <slug>   Show a requirement's change history + diffs
+            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
             attachments <slug> <id>           Get download URL for an attachment

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.
@@ -303,6 +321,7 @@ module Fp
           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
           ```
 
           **The requirement catalog is the human-readable product specification, not a box to

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
@@ -106,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?

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'

data/lib/fp/version.rb

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

data/skills/fp/SKILL.md

@@ -49,6 +49,7 @@ fp list --project stowzilla --status draft     # Proposed work; avoid duplicates
 fp list --project stowzilla --gaps             # Requirements with a required surface lacking evidence
 fp show <slug> --project stowzilla             # Requirement details and evidence
 fp history <slug> --project stowzilla          # Origins and pending changes
+fp changes --source-url <work-item-url>         # Activity prompted by one card, issue, or thread
 fp matrix --project stowzilla                  # ASCII parity matrix
 fp matrix --project stowzilla --csv            # Export as CSV
 fp check --project stowzilla                   # Enforce parity (exits 1 on violations)
@@ -332,6 +333,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` |
+| 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` |
 | View matrix | `fp matrix --project X` |

data/skills/fp/references/cli.md

@@ -270,6 +270,31 @@ 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 changes
+
+Show requirement activity prompted by a work item, rather than opening every requirement's
+history separately.
+
+```bash
+fp changes --source-url https://app.fizzy.do/6098707/cards/1434
+fp changes --project stowzilla --source-url https://github.com/acme/app/issues/42
+fp changes --github-pr --github-summary
+```
+
+`--source-url` may be repeated. The API matches the URL exactly against the source recorded
+when a requirement was created, directly edited, proposed for modification, or proposed for
+removal. Results include the requirement, activity kind, review state, actor, and a link to the
+requirement.
+
+In a GitHub pull-request workflow, `--github-pr` reads the live PR through the GitHub API and
+writes or replaces one marker-managed requirement table in its description. It requires
+`GITHUB_TOKEN`, `GITHUB_REPOSITORY`, `GITHUB_EVENT_PATH`, and `pull-requests: write`; inability
+to read or update the PR is an error, so a missing table cannot silently pass. Add
+`--github-summary` to keep the same table in `GITHUB_STEP_SUMMARY`. A PR with no linked work
+item says FeatureParity cannot determine the activity; a linked work item with no events
+explicitly says no requirement changes were recorded. Generated `fp init` workflows configure
+both outputs before the parity gate.
+
 ### fp matrix
 
 Display the parity matrix. Cells show the state of the evidence filed for each
@@ -373,7 +398,7 @@ fp init --project stowzilla --dir path/to/repo
 | File | Purpose |
 |------|---------|
 | `.featureparity.yml` | declares the project slug, so `--project` becomes optional |
-| `.github/workflows/feature-parity.yml` | the CI gate |
+| `.github/workflows/feature-parity.yml` | the CI gate and PR requirement-change summary |
 | `AGENTS.md` (appended) | instructions telling agents to mark and report their tests |
 
 Existing files are skipped unless `--force`. The `AGENTS.md` section is appended between

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: featureparity
 version: !ruby/object:Gem::Version
-  version: 0.0.15
+  version: 0.0.16
 platform: ruby
 authors:
 - Stowzilla
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-10-09 00:00:00.000000000 Z
+date: 2026-10-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: net-http
@@ -97,6 +97,7 @@ files:
 - lib/fp/commands/attach.rb
 - lib/fp/commands/attachments.rb
 - lib/fp/commands/base.rb
+- lib/fp/commands/changes.rb
 - lib/fp/commands/check.rb
 - lib/fp/commands/ci_report.rb
 - lib/fp/commands/config_cmd.rb