featureparity 0.0.7 → 0.0.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d668266132dc93de82fc60d7603f340ab05a8e5852fa4cde36ce9e6e4586ff18
-  data.tar.gz: 7d1b2691eeade5eabf110c518dca40808ce1beee2a0809b422376eaf914692c4
+  metadata.gz: c622199401f105760e517583ace2bb9ec9da7f6f125d960144783ec82e2922b4
+  data.tar.gz: ab0b372febeff5b863f46d80d093ff8ac789bb4fdd2ae9ceab443f81a8b9a2f5
 SHA512:
-  metadata.gz: dafb288e14865ffd01b3cf739a510b8c7c2cf103b5e0867b07ce8f79264a14e8ab34ef95a01a73a77c3566adc2ce792488a3581f8ca184f1cd9b0678f8a4bce2
-  data.tar.gz: eee75e4d691fbd6884b0d417a1e8a9ae8c88e15da95ad1919b64f9a7e6a1ed915a5a8baa2687603cbe9d41a3f27738d4b0ae360d3ec97efb0885c45e62b4bcaf
+  metadata.gz: ed416b54e77e1aa6e9ce490283811ac5b81443f34aef97cf9b47987719bc5b5497456c4fd3bb74b1f308b735ab07bc5682a06a4d13548cd48272135160692cd2
+  data.tar.gz: 6316ceda063c279ad46dd763c5ab9b1366a27cd00c1eb8d6f52b7ce21995c203040f86667e76a4a921e77d7a14c380ec85aaedb1ad0c4468e8284b185cf69a5c

data/lib/fp/client.rb

@@ -33,11 +33,12 @@ module Fp
     end
 
     # GET /requirements
-    def list_requirements(project_id: nil, status: nil, category: nil)
+    def list_requirements(project_id: nil, status: nil, category: nil, tag: nil)
       params = {}
       params[:project_id] = project_id if project_id
       params[:status] = status if status
       params[:category] = category if category
+      params[:tag] = tag if tag
       get('/api/requirements', params)
     end
 
@@ -118,12 +119,16 @@ module Fp
     # writes passing/failing evidence per surface. It also marks previously
     # passing slugs that have vanished from the results as failing. This is the
     # half of the loop only CI is allowed to close (#1222).
-    def ingest_ci_results(project_id, ci_url:, surface:, junit_xml:)
-      post("/api/projects/#{project_id}/ci_results", {
-             ci_url: ci_url,
-             surface: surface,
-             junit_xml: junit_xml
-           })
+    def ingest_ci_results(project_id, ci_url:, surface:, junit_xml:, pr_url: nil)
+      body = {
+        ci_url: ci_url,
+        surface: surface,
+        junit_xml: junit_xml
+      }
+      # Only send pr_url when set, so a merged-branch run stays a plain ingest.
+      body[:pr_url] = pr_url if pr_url && !pr_url.empty?
+
+      post("/api/projects/#{project_id}/ci_results", body)
     end
 
     # GET /projects/:project_id/parity — the computed parity grid and gate verdict.

data/lib/fp/commands/ci_report.rb

@@ -25,11 +25,18 @@ module Fp
     # Multiple --junit flags may be passed to ingest several reports for the same
     # surface in one invocation (e.g. a suite split across shards). Each is
     # uploaded in turn.
+    #
+    # --pr <url> marks the run as a pull request's CI rather than the merged branch's.
+    # Passing tests are then recorded as `pr_passing` ("would pass once merged") instead
+    # of `passing`, and no merged evidence is demoted. Run it without --pr on pushes to
+    # the default branch to record the real `passing`, superseding any pr_passing a prior
+    # PR run left behind.
     class CiReport < Base
       KNOWN_FLAGS = {
         project: :string,
         surface: :string,
         ci_url: :string,
+        pr: :string,
         junit: :string
       }.freeze
 
@@ -64,7 +71,8 @@ module Fp
             project_id,
             ci_url: opts[:ci_url],
             surface: opts[:surface],
-            junit_xml: xml
+            junit_xml: xml,
+            pr_url: opts[:pr]
           )
 
           unless result[:ok]
@@ -92,6 +100,7 @@ module Fp
           project: opts[:project],
           surface: opts[:surface],
           ci_url: opts[:ci_url],
+          pr_url: opts[:pr],
           evidence_created: totals[:created],
           evidence_updated: totals[:updated],
           missing_marked_failing: totals[:missing_failing],
@@ -99,11 +108,11 @@ module Fp
         }
 
         output.success(data) do
-          puts "Ingested CI results for surface '#{opts[:surface]}':"
+          mode = opts[:pr] ? " (PR mode — passing tests recorded as pr_passing)" : ''
+          puts "Ingested CI results for surface '#{opts[:surface]}'#{mode}:"
           totals[:reports].each do |report|
             report[:results].each do |r|
-              glyph = r['status'] == 'passing' ? '✓' : (r['status'] == 'failing' ? '✗' : '•')
-              puts "  #{glyph} #{r['slug']}  (#{r['status']})  #{r['source_file']}"
+              puts "  #{Parity.glyph(r['status'])} #{r['slug']}  (#{r['status']})  #{r['source_file']}"
             end
           end
           puts

data/lib/fp/commands/help.rb

@@ -25,6 +25,7 @@ module Fp
             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
@@ -61,6 +62,14 @@ module Fp
             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:
 
@@ -124,6 +133,9 @@ module Fp
             # List requirements filtered by category
             fp list --project stowzilla --category security
 
+            # 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
@@ -132,13 +144,23 @@ module Fp
             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.

data/lib/fp/commands/init.rb

@@ -309,6 +309,19 @@ 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.
+
           ### 2. If the requirement is wrong, propose a change — don't silently edit it
 
           Shipping something that contradicts a requirement means one of the two is wrong.

data/lib/fp/commands/list.rb

@@ -9,6 +9,7 @@ module Fp
         project: :string,
         surface: :string,
         category: :string,
+        tag: :string,
         status: :string,
         gaps: :boolean
       }.freeze
@@ -33,7 +34,7 @@ module Fp
       private
 
       def list_requirements(project_id, opts)
-        result = client.list_requirements(project_id: project_id, category: opts[:category])
+        result = client.list_requirements(project_id: project_id, category: opts[:category], tag: opts[:tag])
 
         unless result[:ok]
           output.error(result[:error], status: result[:status])
@@ -66,6 +67,7 @@ module Fp
           if requirements.empty?
             filter_desc = [status_filter]
             filter_desc << "category: #{opts[:category]}" if opts[:category]
+            filter_desc << "tag: #{opts[:tag]}" if opts[:tag]
             filter_desc << "surface: #{opts[:surface]}" if opts[:surface]
             puts "No requirements found (#{filter_desc.join(', ')})."
           else
@@ -79,19 +81,21 @@ module Fp
             parent_ids = parents.map { |p| p['id'] }.to_set
             orphans = requirements.select { |r| r['parent_id'] && r['parent_id'] != '' && !parent_ids.include?(r['parent_id']) }
 
-            headers = %w[SLUG TITLE CATEGORY SURFACES STATUS]
+            headers = %w[SLUG TITLE CATEGORY TAGS SURFACES STATUS]
             rows = []
 
             parents.each do |r|
               surfaces = (r['required_surfaces'] || []).join(', ')
               category = r['category'] || '-'
-              rows << [r['slug'], truncate(r['title'], 40), category, surfaces.empty? ? '-' : surfaces, status_cell(r)]
+              tags = (r['tags'] || []).join(', ')
+              rows << [r['slug'], truncate(r['title'], 40), category, tags.empty? ? '-' : tags, surfaces.empty? ? '-' : surfaces, status_cell(r)]
 
               # Add children indented
               (children_by_parent[r['id']] || []).each do |child|
                 child_surfaces = (child['required_surfaces'] || []).join(', ')
                 child_category = child['category'] || '-'
-                rows << ["  └ #{child['slug']}", truncate(child['title'], 36), child_category, child_surfaces.empty? ? '-' : child_surfaces, status_cell(child)]
+                child_tags = (child['tags'] || []).join(', ')
+                rows << ["  └ #{child['slug']}", truncate(child['title'], 36), child_category, child_tags.empty? ? '-' : child_tags, child_surfaces.empty? ? '-' : child_surfaces, status_cell(child)]
               end
             end
 
@@ -99,7 +103,8 @@ module Fp
             orphans.each do |r|
               surfaces = (r['required_surfaces'] || []).join(', ')
               category = r['category'] || '-'
-              rows << [r['slug'], truncate(r['title'], 40), category, surfaces.empty? ? '-' : surfaces, status_cell(r)]
+              tags = (r['tags'] || []).join(', ')
+              rows << [r['slug'], truncate(r['title'], 40), category, tags.empty? ? '-' : tags, surfaces.empty? ? '-' : surfaces, status_cell(r)]
             end
 
             output.table(headers, rows)

data/lib/fp/commands/propose.rb

@@ -16,7 +16,8 @@ module Fp
         category: :string,
         source_type: :string,
         source_url: :string,
-        source_context: :string
+        source_context: :string,
+        tags: :string
       }.freeze
 
       VALID_CATEGORIES = %w[functional non-functional ux performance security compliance].freeze
@@ -62,6 +63,12 @@ module Fp
         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])
@@ -85,6 +92,7 @@ module Fp
           puts "  Title:    #{requirement['title']}"
           puts "  Status:   #{requirement['status']}"
           puts "  Category: #{requirement['category'] || '(none)'}"
+          puts "  Tags:     #{(requirement['tags'] || []).join(', ')}" unless (requirement['tags'] || []).empty?
           puts "  Surfaces: #{(requirement['required_surfaces'] || []).join(', ')}"
           puts "  Parent:   #{opts[:parent] || '(none)'}" if opts[:parent]
           puts

data/lib/fp/commands/report.rb

@@ -116,6 +116,9 @@ module Fp
           if opts[:pr]
             puts "  PR:    #{opts[:pr]}"
           end
+          if opts[:sha]
+            puts "  SHA:   #{opts[:sha]}"
+          end
           if opts[:work_item]
             puts "  Work:  #{opts[:work_item]}"
           end

data/lib/fp/commands/show.rb

@@ -67,6 +67,8 @@ module Fp
         puts "Slug:     #{req['slug']}"
         puts "Status:   #{req['status']}"
         puts "Category: #{req['category'] || '(none)'}"
+        tags = req['tags'] || []
+        puts "Tags:     #{tags.empty? ? '(none)' : tags.join(', ')}"
         puts "Parent:   #{parent_slug || req['parent_id'] || '(none)'}"
         puts
 
@@ -110,6 +112,7 @@ module Fp
                   puts "    File:    #{loc}"
                 end
                 puts "    Repo:    #{e['repo']}" if e['repo']
+                puts "    Commit:  #{e['commit_sha']}" if e['commit_sha']
                 puts "    PR:      #{e['pr_url']}" if e['pr_url']
                 puts "    Work:    #{e['work_item_url']}" if e['work_item_url']
                 puts "    CI:      #{e['ci_url']}" if e['ci_url']

data/lib/fp/parity.rb

@@ -17,10 +17,11 @@ module Fp
   # here rather than changing any verdict.
   module Parity
     # Worst → best, matching the server's severity order. Used for stable output.
-    STATES = %w[failing missing suspect stub present passing].freeze
+    STATES = %w[failing missing suspect stub present pr_passing passing].freeze
 
     GLYPHS = {
       'passing' => '✓',
+      'pr_passing' => '◐',
       'failing' => '✗',
       'present' => '●',
       'stub' => '○',
@@ -42,7 +43,7 @@ module Fp
 
     LEVELS = %w[off regression covered strict].freeze
 
-    LEGEND = 'Legend: ✓ passing  ✗ failing  ● present  ○ stub  ⚠ suspect  · missing  - not required'
+    LEGEND = 'Legend: ✓ passing  ◐ pr-passing  ✗ failing  ● present  ○ stub  ⚠ suspect  · missing  - not required'
 
     # Appended to the legend only when the grid actually contains one, so the common
     # case isn't cluttered by vocabulary nothing on screen uses.

data/lib/fp/version.rb

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

data/skills/fp/SKILL.md

@@ -112,11 +112,24 @@ fp report --junit junit.xml \
 fp propose --project stowzilla \
   --slug print_container_qr \
   --name "Print QR on container label" \
-  --why "Enables scanning containers in the warehouse" \
+  --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 \
-  --acceptance "Label shows scannable QR code"
+  --acceptance "QR scans to the container's detail page"
 ```
 
+**Writing `--why`: brief, and it actually explains why.** Whoever approves this
+requirement should 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 "Staff scan the label to find a container; without a QR they key the ID by hand and mis-type it."`
+- ❌ `--why "Ensures a high-quality experience 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`: the observable condition that proves it's done, not a
+restatement of the title.
+
 **Agents always create requirements as draft.** A human must activate in the web app.
 
 ### 6. Propose a change to an existing requirement

data/skills/fp/references/cli.md

@@ -136,9 +136,9 @@ Propose a new requirement as draft.
 fp propose --project stowzilla \
   --slug print_container_qr \
   --name "Print QR on container label" \
-  --why "Enables scanning 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 \
-  --acceptance "Label shows scannable QR code"
+  --acceptance "QR scans to the container's detail page"
 ```
 
 | Flag | Required | Description |
@@ -146,9 +146,18 @@ fp propose --project stowzilla \
 | `--project` | Yes | Project slug |
 | `--slug` | Yes | Requirement slug (immutable, choose carefully) |
 | `--name` | Yes | Human-readable name |
-| `--why` | No | Why this requirement matters |
+| `--why` | No | One plain sentence: the user need or outcome the feature serves (see below) |
 | `--required` | No | Comma-separated surfaces that must implement this |
-| `--acceptance` | No | How to verify completion |
+| `--acceptance` | No | The observable condition that proves it's done |
+
+**Writing `--why`:** brief, and it actually explains why. Whoever approves this 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.
+
+- ✅ `"Staff scan the label to find a container; without a QR they key the ID by hand and mis-type it."`
+- ❌ `"Ensures a high-quality experience across all surfaces."` (filler)
+- ❌ `"The label renders a QR image encoding the container ID at print time."` (how it works, not why)
 
 **Agents always create requirements as draft.** A human must activate in the web app.
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: featureparity
 version: !ruby/object:Gem::Version
-  version: 0.0.7
+  version: 0.0.8
 platform: ruby
 authors:
 - Stowzilla