featureparity 0.0.6 → 0.0.8

data/lib/fp/commands/help.rb

@@ -12,16 +12,23 @@ module Fp
             fp <command> [flags]
 
           COMMANDS
+            init --project <slug>             Onboard this repo: config, CI gate, agent docs
             projects                          List projects you have access to
             surfaces --project <slug>         List surfaces for a project
             surfaces add <key> --project ...  Create a surface
             list --project <slug>             List active requirements
             show <slug> --project <slug>      Show requirement details
             propose --project <slug> ...      Propose a new requirement (as draft)
+            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
             report <slug> --project <slug>... Report evidence for a requirement
             report --junit <file> ...         Upload evidence from a JUnit XML report (no CI)
             ci-report --junit <file> ...      Ingest CI test results (passing/failing) — CI only
+            ci-report --junit <file> --pr URL Ingest a PR's CI results as pr_passing — CI only
+            check                             Enforce parity; exits non-zero on violations
             matrix --project <slug>           Show the parity matrix
+            export --project <slug>           Export all requirements as a Markdown document
             profile add|list                  Manage named profiles
             config set|get|unset|list         Manage global settings
             whoami                            Show the resolved config (profile, env, API URL, key)
@@ -36,6 +43,33 @@ module Fp
             -p <name>                         Alias for --profile
             --api-url <url>                   Override API URL for this command
 
+          PROJECT RESOLUTION
+            Commands that act on a project take --project <slug>. If you omit it, fp reads
+            `project:` from the nearest .featureparity.yml at or above the working directory,
+            so a checkout declares its own project once instead of every CI job and agent
+            repeating it. `fp init` writes that file.
+
+          ENFORCEMENT
+            `fp check` fails a build when the project violates its enforcement level. Make it
+            a required status check on your default branch to block merges.
+
+              off          Report only; nothing fails.
+              regression   A test that has gone red fails the build. Missing coverage does not.
+              covered      Every required surface needs real (non-stub) evidence.
+              strict       Every required surface must be green in CI.
+
+            The level lives on the project server-side, so raising it takes effect everywhere
+            at once. `--level` overrides it for one run; `--warn-only` reports violations but
+            still exits 0, for adopting the gate on a repo that isn't clean yet.
+
+          PR-VERIFIED EVIDENCE
+            `ci-report --pr <url>` marks a run as a pull request's CI. Passing tests are then
+            recorded as `pr_passing` ("would pass once merged") instead of `passing`, and no
+            merged evidence is demoted. It ranks between `present` and `passing`: it counts as
+            covered at the `covered` level, but only `strict` accepts it — strict wants the
+            merged-green truth. Run ci-report *without* --pr on a push to the default branch to
+            record the real `passing`, which supersedes any pr_passing a prior PR left behind.
+
           AUTHENTICATION
             Set FP_API_KEY environment variable, or use a profile:
 
@@ -59,6 +93,20 @@ module Fp
             # First-time setup (interactive)
             fp setup
 
+            # Onboard a repo onto FeatureParity: writes .featureparity.yml, a CI gate
+            # workflow, and a FeatureParity section in AGENTS.md telling agents to mark
+            # and report their tests. Needs no API key.
+            fp init --project stowzilla --surface api
+            fp init --project stowzilla --no-workflow      # skip the CI workflow
+            fp init --project stowzilla --force            # refresh previously written files
+
+            # Enforce parity. Exits 1 on violations, so CI blocks the merge.
+            fp check                                       # project from .featureparity.yml
+            fp check --project stowzilla --surface api      # gate one surface only
+            fp check --level covered                        # demand coverage, not just no regressions
+            fp check --warn-only                            # report violations but exit 0
+            fp check --json                                 # machine-readable violations
+
             # Show the resolved configuration (which profile/env/API URL/key is in effect)
             fp whoami
             fp whoami --json
@@ -85,20 +133,34 @@ module Fp
             # List requirements filtered by category
             fp list --project stowzilla --category security
 
-            # Show gaps (requirements without evidence)
+            # List requirements filtered by tag (free-form label)
+            fp list --project stowzilla --tag mobile
+
+            # Show gaps: requirements with a required surface that has no real evidence
+            # (missing, stubbed, or failing). Unlike `fp list`, this reads evidence.
             fp list --project stowzilla --gaps --surface customer_android
 
             # Show a specific requirement
             fp show print_container_qr --project stowzilla
 
             # Propose a new requirement (creates as draft)
+            #
+            # --why must be brief and actually explain why: whoever approves it should grasp
+            # in one read the user need or outcome the feature serves. Longer is fine when it
+            # earns its length; wordy is not. Avoid filler, and avoid describing HOW it works
+            # instead of WHY anyone wants it.
+            #   good: "Staff scan the label to find a container; without a QR they key the ID by hand and mis-type it."
+            #   bad:  "Ensures a high-quality experience across all surfaces." (filler)
+            # --acceptance is the observable condition that proves it's done, not a
+            # restatement of the title.
             fp propose --project stowzilla \\
               --slug print_container_qr \\
               --name "Print QR code on container label" \\
-              --why "Customers scan to track containers" \\
+              --why "Staff scan the label to find a container; without a QR they key the ID by hand and mis-type it" \\
               --required api,customer_android,customer_ios \\
-              --acceptance "QR code is printed and scannable" \\
-              --category functional
+              --acceptance "QR scans to the container's detail page" \\
+              --category functional \\
+              --tags mobile,labeling,q3
 
             # Nest a requirement under a parent (--parent takes the parent's SLUG).
             # A child's --required surfaces must be a subset of its parent's.
@@ -108,10 +170,30 @@ module Fp
               --parent print_container_qr \\
               --required customer_ios
 
+            # Propose a change to a requirement that already exists. Say what prompted it
+            # — the card, the thread, the issue. The requirement drops back to DRAFT and a
+            # human reviews the old-vs-new diff before it counts again.
+            fp propose-change print_container_qr --project stowzilla \\
+              --why "Labels must survive a freezer" \\
+              --acceptance "QR scans after 24h at -20C" \\
+              --reason "Cold-chain rollout" \\
+              --source-type fizzy \\
+              --source-url https://app.fizzy.do/6098707/cards/1377
+
+            # Propose deleting a requirement (nothing is destroyed — a human decides)
+            fp propose-change print_container_qr --project stowzilla \\
+              --removal \\
+              --reason "Superseded by print_container_label"
+
+            # See what changed, why, and who asked for it
+            fp history print_container_qr --project stowzilla
+            fp history print_container_qr --project stowzilla --pending
+
             # Report evidence for a requirement
             fp report print_container_qr --project stowzilla \\
               --surface customer_android \\
               --file app/src/test/java/PrintQrTest.kt \\
+              --line 42 \\
               --repo stowzilla/customer-android \\
               --pr https://github.com/stowzilla/customer-android/pull/123 \\
               --work-item https://app.fizzy.do/123/cards/456 \\
@@ -144,6 +226,13 @@ module Fp
             # Export matrix as CSV
             fp matrix --project stowzilla --csv > matrix.csv
 
+            # Export the full requirements document as Markdown
+            fp export --project stowzilla > requirements.md
+
+            # Export only active requirements for one surface, written to a file
+            fp export --project stowzilla --status active \\
+              --surface customer_android --output requirements.md
+
             # Map a surface to a local repo on this machine
             fp repos set customer_android ~/code/customer-android \\
               --project stowzilla --repo stowzilla/customer-android

data/lib/fp/commands/history.rb

@@ -0,0 +1,188 @@
+# frozen_string_literal: true
+
+module Fp
+  module Commands
+    # `fp history <slug>` — the change history of a requirement: what it was, what
+    # changed, who changed it, and what prompted the change.
+    #
+    # Reads as a timeline (oldest first) so it can be scanned top to bottom. The open
+    # proposal, if there is one, is called out at the end because that's the thing
+    # someone still has to decide on.
+    class History < Base
+      KNOWN_FLAGS = { project: :string, pending: :boolean, limit: :string }.freeze
+
+      # Human labels for event types. The wire values are stable identifiers; these are
+      # for reading.
+      TYPE_LABELS = {
+        'created' => 'created',
+        'updated' => 'edited',
+        'activated' => 'approved',
+        'archived' => 'archived',
+        'destroyed' => 'deleted',
+        'change_proposed' => 'change proposed',
+        'removal_proposed' => 'deletion proposed',
+        'change_approved' => 'change approved',
+        'change_rejected' => 'change rejected'
+      }.freeze
+
+      def run(args)
+        opts, positional = parse_flags(args, KNOWN_FLAGS)
+        require_project!(opts)
+
+        slug = positional.first
+        unless slug
+          output.error('Requirement slug is required. Usage: fp history <slug> [--project <project>]')
+          exit 1
+        end
+
+        project_id = resolve_project_id(opts[:project])
+        requirement = find_requirement!(project_id, slug)
+
+        result = client.list_requirement_changes(requirement['id'])
+        unless result[:ok]
+          output.error(result[:error], status: result[:status])
+          exit 1
+        end
+
+        changes = result[:data]['changes'] || []
+        pending = result[:data]['pending_change']
+
+        changes = changes.select { |c| c['pending'] } if opts[:pending]
+        changes = changes.last(opts[:limit].to_i) if opts[:limit].to_s =~ /\A\d+\z/
+
+        payload = { 'requirement' => requirement, 'changes' => changes, 'pending_change' => pending }
+
+        output.success(payload) do
+          print_history(slug, changes, pending)
+        end
+      end
+
+      private
+
+      def find_requirement!(project_id, slug)
+        result = client.find_requirement_by_slug(project_id, slug)
+        unless result[:ok]
+          output.error(result[:error], status: result[:status])
+          exit 1
+        end
+        result[:data]['requirement']
+      end
+
+      def print_history(slug, changes, pending)
+        heading = "History: #{slug}"
+        puts heading
+        puts '=' * heading.length
+        puts
+
+        if changes.empty?
+          puts '  (no recorded changes)'
+          puts
+        else
+          changes.each { |change| print_entry(change) }
+        end
+
+        print_pending(pending)
+      end
+
+      def print_entry(change)
+        label = TYPE_LABELS[change['type']] || change['type']
+        actor = change['actor'] || 'unknown'
+        kind = change['actor_kind'] == 'agent' ? 'agent' : 'human'
+
+        puts "* #{label} — #{actor} (#{kind}) at #{format_time(change['recorded_at'])}"
+        puts "  #{change['reason']}" if present?(change['reason'])
+        print_source(change['source'])
+        print_diff(change['changes'])
+        print_evidence_diff(change['evidence_diff'])
+        print_review(change['review'])
+        puts
+      end
+
+      def print_source(source)
+        return if source.nil? || source.empty?
+
+        bits = []
+        bits << source['type'] if present?(source['type'])
+        bits << source['url'] if present?(source['url'])
+        puts "  prompted by: #{bits.join(' ')}" unless bits.empty?
+        puts "  context: #{source['context']}" if present?(source['context'])
+      end
+
+      def print_diff(changes)
+        return if changes.nil? || changes.empty?
+
+        changes.each do |field, change|
+          puts "  #{field}:"
+          puts "    - #{format_value(change['from'])}"
+          puts "    + #{format_value(change['to'])}"
+        end
+      end
+
+      # The test-evidence half of the diff: what coverage existed when the change was
+      # proposed versus what exists now (or existed at review time).
+      def print_evidence_diff(diff)
+        return if diff.nil?
+
+        added = diff['added'] || []
+        removed = diff['removed'] || []
+        changed = diff['changed'] || []
+        return if added.empty? && removed.empty? && changed.empty?
+
+        puts '  evidence:'
+        added.each { |e| puts "    + #{describe_evidence(e)}" }
+        removed.each { |e| puts "    - #{describe_evidence(e)}" }
+        changed.each do |c|
+          before = c['before'] || {}
+          after = c['after'] || {}
+          puts "    ~ #{after['surface']} #{after['source_file']} " \
+               "(#{before['status']} → #{after['status']})"
+        end
+      end
+
+      def describe_evidence(evidence)
+        parts = [evidence['surface'], evidence['source_file']].compact
+        status = evidence['status']
+        status ? "#{parts.join(' ')} (#{status})" : parts.join(' ')
+      end
+
+      def print_review(review)
+        return if review.nil? || review.empty?
+
+        puts "  reviewed: #{review['decision']} by #{review['actor']} at #{format_time(review['at'])}"
+        puts "  note: #{review['note']}" if present?(review['note'])
+      end
+
+      def print_pending(pending)
+        if pending.nil?
+          puts 'No change awaiting review.'
+          return
+        end
+
+        kind = pending['kind'] == 'removal' ? 'DELETION' : 'CHANGE'
+        puts "⚠️  #{kind} AWAITING REVIEW (#{pending['id']})"
+        puts "   Proposed by #{pending['actor']} at #{format_time(pending['recorded_at'])}."
+        puts '   A human must approve or reject it in the web app.'
+      end
+
+      # Timestamps are recorded at nanosecond precision for ordering; that's noise to
+      # read, so trim to seconds.
+      def format_time(value)
+        return '(unknown)' unless present?(value)
+
+        value.to_s.sub(/\.\d+/, '')
+      end
+
+      def format_value(value)
+        case value
+        when nil then '(none)'
+        when Array then value.empty? ? '(none)' : value.join(', ')
+        else value.to_s
+        end
+      end
+
+      def present?(value)
+        !value.nil? && !value.to_s.strip.empty?
+      end
+    end
+  end
+end