featureparity 0.0.25 → 0.0.27

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a7a4558cdeaa90d0b4197daca351b9eadbeee5af21cb8454e9a1f44b3725bbaa
-  data.tar.gz: d0134aeca43dd6ee3415bfafe25ea7f67212eda1b8577a3bdfd9d9a3800aa150
+  metadata.gz: 4b09491a1b44b4ba693dfd567cdec5068d3410c577066435b541b2e9520ae04f
+  data.tar.gz: c9b7fb84bee3dbb3e8dfd8ee29f7c4d878747c0157efaa63fb020ead7934b2e7
 SHA512:
-  metadata.gz: 70827aadfd85037c992e670923ae4c7065c6ba913905028b903f4b6535f8498f530d3ec51a9ff245aa9734a3f044d6ca779b5e8b849b0a15d1b6b2aaed360e2f
-  data.tar.gz: 9ba46d5f8efa5a57e4b23c2557969cdd5c6b6697cb8584bb98b7c11fc237a099743c33474b46d05444361785278707981206af09e7c32570261ae5b104a9885d
+  metadata.gz: cdf6cc31e230d20555285da1b44ee1816e94a88d3a5e3c02b22569cc63034d2f038d5183c12191f9ba446e5fdbc78a44ebe0b485e476f0dd5b9e021675338500
+  data.tar.gz: c9b9337383f9e7aecfa8caec130d99e3a1e93452481d14ffe1e0f95bd63c495480241d3b1578f0ff01ca5c7f81cc3b969a78cf232947a563cd307ade34b255c1

data/lib/fp/client.rb

@@ -281,7 +281,7 @@ module Fp
     # only do that by fetching the test files from GitHub, which fails silently on a
     # private repo, so resolved results are always sent when we have them.
     def ingest_ci_results(project_id, ci_url:, surface:, junit_xml:, pr_url: nil, results: nil,
-                          test_revisions: nil, unmarked_failures: nil, orphan_markers: nil)
+                          test_revisions: nil, unmarked_failures: nil, orphan_markers: nil, sha: nil)
       body = {
         ci_url: ci_url,
         surface: surface,
@@ -289,6 +289,9 @@ module Fp
       }
       # 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?
+      # The checkout commit, so the receipt (or a PR run's branch verdict) links the
+      # exact revision the suite ran at.
+      body[:sha] = sha if sha && !sha.empty?
       body[:results] = results if results && !results.empty?
       # Testcase-level source receipts stay separate from aggregate Evidence outcomes:
       # several tests may back one cell, and each can change independently.

data/lib/fp/commands/ci_report.rb

@@ -146,6 +146,7 @@ module Fp
           # with servers old enough to ignore client-resolved results.
           junit_xml: resolved_reports.first[:xml],
           pr_url: opts[:pr],
+          sha: commit_sha,
           results: combined_results,
           test_revisions: combined_revisions,
           unmarked_failures: totals[:unmarked_failures],

data/lib/fp/commands/help.rb

@@ -289,24 +289,32 @@ module Fp
             #
             # Write the requirement as a product decision someone can approve, not a design
             # task. It should sound like a capable teammate, not AI boilerplate.
-            #   title: one product promise in present tense, not the implementation project
-            #   why: one or two natural sentences naming the user need/problem and outcome
-            #   acceptance: trigger or situation + observable result + material boundaries
-            # Use examples and tests to ground and double-check the general rule, not to replace
-            # it or ongoing conversation. Leave out components, data models, algorithms, endpoints,
-            # and UI controls unless they are themselves part of the user-visible contract.
-            # Include a price, quota, timeout, count, date,
-            # role, or fallback only when the source made it a real product decision; if an
-            # important policy is missing, ask instead of inventing a plausible value.
+            #   title: one product promise in present tense, with a concrete subject and active verb
+            #   why: one natural sentence naming the user need/problem and protected outcome
+            #   acceptance: one independently verifiable rule of observable behaviour;
+            #               append one concise concrete case as "Example: ..."
+            # Given/When/Then may clarify a rule, but is not mandatory. Split another result that
+            # could fail independently rather than comma-chaining it into the same requirement.
+            # Use the domain's real terms in examples and ask rather than invent consequential
+            # policy. Examples and tests ground and double-check the rule; they do not replace it.
+            # State each field directly. Avoid “This feature…”, “The goal is…”, “Users should be
+            # able to…”, “The system should…”, and task titles beginning “Enable” or “Implement”.
+            # Leave out components, data models, algorithms, endpoints, and UI controls unless
+            # they are themselves part of the user-visible contract.
+            # Include a price, quota, timeout, count, date, role, or fallback only when the source
+            # made it a real product decision; if important policy is missing, ask instead of
+            # inventing a plausible value.
             #
             #   good title:      "Dispatchers see current shipment status"
             #   good why:        "Dispatchers need to spot delayed shipments before they miss a delivery window."
             #   good acceptance: "When status changes, the dashboard shows it; when unavailable, it says so instead of showing stale data as current."
             #   bad: "Implement Redis polling every 30 seconds to ensure a seamless experience."
             #        (invented policy, implementation detail, and filler; no product outcome)
-            # Before saving, read it as a manager deciding scope: is the value clear, is the
-            # result observable, are decisions separated from guesses, and does every sentence
-            # earn its place?
+            # Before saving, answer against the actual fields: who is this promise for, how would
+            # the concrete example prove it done, and why does the outcome matter? If an answer is
+            # vague, revise or ask. Then read it as a manager deciding scope: is the value clear,
+            # is the result observable, are decisions separated from guesses, and does every
+            # sentence earn its place? Do not save until the draft passes this review.
             fp propose --project stowzilla \\
               --slug print_container_qr \\
               --name "Print QR code on container label" \\

data/lib/fp/commands/init.rb

@@ -470,18 +470,22 @@ module Fp
           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.
+          - **Title:** one clear product promise in present tense, with a concrete subject and
+            active verb. Name the user-visible capability, not the work (`“Dispatchers see
+            current shipment status”`, not `“Implement status polling”`).
+          - **Why:** one natural sentence naming who needs this, the problem or risk, and the
+            outcome worth protecting. Do not repeat the title, narrate the request or bug
+            history, sell the feature, or explain the mechanism.
+          - **Acceptance:** one independently verifiable rule of observable behaviour that lets a
+            reviewer decide whether the promise is true. State the trigger or situation, the result, and material
+            boundaries that qualify that same promise. Given/When/Then may clarify those parts,
+            but it is not a mandatory template. Split a second result that could fail
+            independently into its own requirement instead of comma-chaining it here.
+          - **Example:** supply one concise concrete case that would pass the general rule, and
+            put it after the rule in Acceptance as `Example: ...`. Use the domain's real terms
+            and representative data, but ask rather than invent consequential policy. Do not mistake a few examples for the rule
+            or let marked 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.
@@ -494,6 +498,10 @@ module Fp
           unquestionable scope. Preserve important uncertainty as a question rather than
           laundering a guess into acceptance criteria.
 
+          State the promise itself rather than commentary about it. Avoid openings such as “This
+          feature…”, “This requirement…”, “The goal is…”, “Users should be able to…”, and “The
+          system should…”. Use the real actor or product as the subject and an active verb.
+
           - ✅ **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.`
@@ -502,9 +510,12 @@ module Fp
             **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.
+          Before proposing, answer three questions against the actual fields: Who is this promise
+          for? How would the concrete example prove it done? Why does the outcome matter? If any
+          answer is missing or vague, revise the draft or ask the user. Then read it as a manager deciding scope:
+          is the value clear, can the result be observed, are product decisions
+          distinguished from guesses, and does every sentence earn its place? If the draft fails
+          this review, revise it or ask before writing the record.
 
           ### 2. If the requirement is wrong, propose a change — don't silently edit it
 

data/lib/fp/commands/report.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require 'open3'
+require 'set'
 require_relative 'attach'
 
 module Fp
@@ -37,11 +39,14 @@ module Fp
       help_flag :junit, 'JUnit XML report to batch-upload evidence from'
       help_flag :base_dir, 'Where relative test-file paths in the report resolve from'
       help_flag :attach_media, 'With --junit: upload the videos/screenshots the run recorded ([[ATTACHMENT|…]]) as visual evidence'
+      help_flag :stamp_all, 'With --junit: put --pr/--work-item on every receipt, not only on tests in files this branch changed'
       help_example 'fp report print_container_qr --project stowzilla --surface api --file spec/qr_spec.rb --repo stowzilla/app'
       help_example 'fp report --junit junit.xml --project stowzilla --surface api --repo stowzilla/app',
                    'Batch-upload from a JUnit report (slugs come from fp:<slug> markers)'
       help_note "Agents report 'present' or 'stub' only. CI writes 'passing'/'failing' via fp ci-report.\n" \
-                'Always pass --test-type when a surface has more than one suite, or they overwrite each other.'
+                "Always pass --test-type when a surface has more than one suite, or they overwrite each other.\n" \
+                'With --junit, --pr and --work-item land only on tests in files this branch changed (git); ' \
+                'the rest of the suite keeps the card and PR that introduced it.'
 
       KNOWN_FLAGS = {
         project: :string,
@@ -58,7 +63,8 @@ module Fp
         state: :string,
         junit: :string,
         base_dir: :string,
-        attach_media: :boolean
+        attach_media: :boolean,
+        stamp_all: :boolean
       }.freeze
 
       VALID_STATES = %w[present stub].freeze
@@ -261,6 +267,12 @@ module Fp
 
         project_id = resolve_project_id(opts[:project])
 
+        # --pr and --work-item say what prompted *this* work. A suite run covers every
+        # marker in the repo, so stamping them on every receipt rewrote the card and PR
+        # on requirements the branch never touched — "View Card" on an unrelated
+        # requirement led to whichever card last ran the suite (Fizzy #1631). Only the
+        # tests in files this branch changed get them; the rest keep their own.
+        provenance = provenance_scope(opts, base_dir)
         reported = []
         skipped_unknown = []
         api_unavailable = false
@@ -289,9 +301,10 @@ module Fp
           }
           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]
+          stamped = provenance.stamps?(binding.file)
+          params[:pr_url] = opts[:pr] if opts[:pr] && stamped
           params[:sha] = opts[:sha] if opts[:sha]
-          params[:work_item_url] = opts[:work_item] if opts[:work_item]
+          params[:work_item_url] = opts[:work_item] if opts[:work_item] && stamped
           params[:ci_url] = opts[:ci_url] if opts[:ci_url]
           params[:title] = binding.title if binding.title
 
@@ -310,7 +323,7 @@ module Fp
             exit 1
           end
 
-          reported << { binding: binding, state: state, recorded: true,
+          reported << { binding: binding, state: state, recorded: true, stamped: stamped,
                         stored_status: stored_status_from(report_result),
                         stored_source: stored_source_from(report_result) }
         end
@@ -321,7 +334,80 @@ module Fp
         end
 
         emit_junit_summary(opts, reported, skipped_unknown, unmatched, api_unavailable, collisions,
-                           empty_name: empty_name, media: media, uploaded_media: uploaded_media)
+                           empty_name: empty_name, media: media, uploaded_media: uploaded_media,
+                           provenance: provenance)
+      end
+
+      # Which receipts of a --junit batch carry --pr/--work-item.
+      #
+      # `files` is the set of repo-relative paths this branch changed — the commits since
+      # it left the default branch, plus anything uncommitted or untracked — or, when
+      # the checkout *is* the default branch, the files in its HEAD commit. Nil means
+      # git couldn't say (not a repository, no default branch to compare with), and then
+      # every receipt is stamped as before, with a note. `--stamp-all` forces that.
+      ProvenanceScope = Struct.new(:mode, :files, keyword_init: true) do
+        def stamps?(file)
+          return true if mode == :all || files.nil?
+
+          files.include?(file.to_s)
+        end
+
+        def scoped?
+          mode != :all && !files.nil?
+        end
+      end
+
+      def provenance_scope(opts, base_dir)
+        return ProvenanceScope.new(mode: :all, files: nil) if opts[:stamp_all]
+        return ProvenanceScope.new(mode: :all, files: nil) if opts[:pr].nil? && opts[:work_item].nil?
+
+        root = Fp::JUnit.repo_root_for(base_dir)
+        return ProvenanceScope.new(mode: :no_git, files: nil) if root.nil?
+
+        head = git_out(root, 'rev-parse', 'HEAD')
+        return ProvenanceScope.new(mode: :no_git, files: nil) if head.nil? || head.empty?
+
+        base = merge_base_with_default_branch(root)
+        committed =
+          if base && base != head
+            git_out(root, 'diff', '--name-only', base, 'HEAD')
+          elsif base
+            # On the default branch itself: the work is whatever this commit touched.
+            git_out(root, 'diff-tree', '--no-commit-id', '--name-only', '-r', '--root', 'HEAD')
+          end
+        return ProvenanceScope.new(mode: :no_git, files: nil) if committed.nil?
+
+        pending = git_out(root, 'diff', '--name-only', 'HEAD') || ''
+        untracked = git_out(root, 'ls-files', '--others', '--exclude-standard') || ''
+        files = [committed, pending, untracked].join("\n").split("\n").map(&:strip).reject(&:empty?).to_set
+        ProvenanceScope.new(mode: (base != head ? :branch : :commit), files: files)
+      end
+
+      # The merge base between HEAD and the default branch, trying origin's HEAD first
+      # and the usual names after it. Nil when none of them exists locally.
+      def merge_base_with_default_branch(root)
+        candidates = []
+        remote_head = git_out(root, 'symbolic-ref', '--short', '-q', 'refs/remotes/origin/HEAD')
+        candidates << remote_head if remote_head && !remote_head.empty?
+        candidates.concat(%w[origin/main origin/master main master])
+        candidates.uniq.each do |ref|
+          verified = git_out(root, 'rev-parse', '--verify', '-q', "#{ref}^{commit}")
+          next if verified.nil? || verified.empty?
+
+          base = git_out(root, 'merge-base', ref, 'HEAD')
+          return base if base && !base.empty?
+        end
+        nil
+      end
+
+      # Stdout of a git command, stripped — '' when it printed nothing, nil on failure.
+      def git_out(root, *args)
+        stdout, _stderr, status = Open3.capture3('git', *args, chdir: root)
+        return nil unless status.success?
+
+        stdout.strip
+      rescue SystemCallError
+        nil
       end
 
       # Upload the media (videos/screenshots) a run recorded for its bound testcases as
@@ -397,10 +483,13 @@ module Fp
       end
 
       def emit_junit_summary(opts, reported, skipped_unknown, unmatched, api_unavailable, collisions = [],
-                             empty_name: [], media: [], uploaded_media: [])
+                             empty_name: [], media: [], uploaded_media: [], provenance: nil)
+        provenance ||= ProvenanceScope.new(mode: :all, files: nil)
+        stamping = !opts[:pr].nil? || !opts[:work_item].nil?
         data = {
           repo: opts[:repo],
-          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], stored_status: r[:stored_status], superseded_by_ci: ci_superseded?(r[:state], r[:stored_status], r[:stored_source]) } },
+          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], stamped: (stamping ? r[:stamped] != false : nil), stored_status: r[:stored_status], superseded_by_ci: ci_superseded?(r[:state], r[:stored_status], r[:stored_source]) }.compact },
+          provenance: (stamping ? { scoped: provenance.scoped?, mode: provenance.mode.to_s, stamped: reported.count { |r| r[:stamped] != false } } : nil),
           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 } },
           empty_name: empty_name,
@@ -423,7 +512,21 @@ module Fp
             loc = r[:binding].line ? "#{r[:binding].file}:#{r[:binding].line}" : r[:binding].file
             type = r[:binding].test_type ? " [#{r[:binding].test_type}]" : ''
             shown_state = superseded ? "#{r[:stored_status]}, kept CI — #{r[:state]} ignored" : r[:state]
-            puts "  #{marker} #{r[:binding].slug} → #{r[:binding].surface}#{type}  (#{shown_state})  #{loc}"
+            stamp = stamping && provenance.scoped? && r[:stamped] ? '  ← this change' : ''
+            puts "  #{marker} #{r[:binding].slug} → #{r[:binding].surface}#{type}  (#{shown_state})  #{loc}#{stamp}"
+          end
+
+          if stamping
+            puts
+            stamped = reported.count { |r| r[:stamped] != false }
+            what = [opts[:pr] && '--pr', opts[:work_item] && '--work-item'].compact.join(' and ')
+            if provenance.scoped?
+              where = provenance.mode == :commit ? 'the files in this commit' : 'the files this branch changed'
+              puts "ℹ️  #{what} recorded on #{stamped} of #{reported.length} receipt(s) — the tests in #{where}."
+              puts '    The rest keep the card and PR that introduced them. Pass --stamp-all to override.'
+            elsif provenance.mode == :no_git
+              puts "ℹ️  #{what} recorded on every receipt: git could not say which files this change touched."
+            end
           end
 
           emit_collision_warning(collisions)

data/lib/fp/commands/show.rb

@@ -164,6 +164,15 @@ module Fp
                 if e['merged_status'] && e['merged_status'] != e['status']
                   puts "    Merged:  #{e['merged_status']} (the default branch's last verdict)"
                 end
+                # An open pull request's CI has reported on this test since the default
+                # branch did. It never changes the status above (Fizzy #1631); it is
+                # the heads-up that a branch says otherwise, with the PR to look at.
+                if e['branch_status']
+                  branch = ["On PR:   #{e['branch_status']}"]
+                  branch << e['branch_pr_url'] if e['branch_pr_url']
+                  branch << '(not merged)'
+                  puts "    #{branch.join(' ')}"
+                end
                 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']

data/lib/fp/version.rb

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

data/skills/fp/SKILL.md

@@ -202,23 +202,33 @@ Before drafting:
 
 Write each field for a reviewer, not for the implementation:
 
-- **Title:** one clear product promise in present tense. Name the capability or outcome, not
-  the project (`Dispatchers see current shipment status`, not `Implement status polling`).
-- **Why:** one or two natural sentences saying who needs this, the problem or risk, and the
-  outcome worth protecting. Do not repeat the title, advertise the feature, or explain how
-  it will be built. Delete AI filler such as “ensure a seamless, robust experience.”
-- **Acceptance:** observable behaviour that lets someone decide whether the promise is true.
-  State the relevant trigger or situation, the result, and material boundaries. Include
-  failure behaviour, permissions, or cross-surface consistency when those affect the promise.
-- **Examples:** use concrete examples or Given/When/Then cases when they clarify a rule or an
-  edge. Examples and executable tests ground and double-check the specification; they do not
-  define every case or replace the general rule and continued conversation.
+- **Title:** one clear product promise in present tense, with a concrete subject and active
+  verb. Name the capability or outcome, not the project (`Dispatchers see current shipment
+  status`, not `Implement status polling`).
+- **Why:** one natural sentence saying who needs this, the problem or risk, and the outcome
+  worth protecting. Do not repeat the title, narrate the request or bug history, advertise
+  the feature, or explain how it will be built. Delete AI filler such as “ensure a seamless,
+  robust experience.”
+- **Acceptance:** one independently verifiable rule of observable behaviour that lets someone
+  decide whether the promise is true. State the relevant trigger or situation, the result, and
+  material boundaries that qualify that same promise. Given/When/Then may clarify those parts, but it
+  is not a mandatory template. Split a second result that could fail independently into its
+  own requirement instead of comma-chaining it here.
+- **Example:** supply one concise concrete case that would pass the general rule, and put it
+  after the rule in Acceptance as `Example: ...`. Use the domain's real terms and
+  representative data, but ask rather than invent consequential policy. Do not mistake a few
+  examples for the rule or let executable tests stand for every case; neither replaces the
+  general rule and continued conversation.
 - **Numbers and policy:** include a number only when the source made it a real product decision
   or an external constraint requires it. Do not invent implementation defaults and present
   them as scope.
 - **Implementation detail:** omit components, data models, algorithms, endpoints, polling
   intervals, and UI controls unless that interface or constraint is itself user-visible policy.
 
+State the promise itself rather than commentary about it. Avoid openings such as “This
+feature…”, “This requirement…”, “The goal is…”, “Users should be able to…”, and “The
+system should…”. Use the real actor or product as the subject and an active verb.
+
 A good requirement is concise, not merely short. Keep every sentence that changes a decision;
 remove everything that only sounds thorough.
 
@@ -230,10 +240,12 @@ remove everything that only sounds thorough.
   **Acceptance:** `Use a background worker and refresh every 30 seconds.`
   This invents policy, prescribes a design, and never states the outcome.
 
-Before saving, read the draft as a manager deciding scope: Is the value clear? Can the result
-be observed? Are real product decisions distinguished from guesses? Could every clause fail
-independently and, if so, should it be split? Does every sentence earn its place? Revise or ask
-before creating the record if the answer is no.
+Before saving, answer three questions against the actual fields: Who is this promise for? How
+would the concrete example prove it done? Why does the outcome matter? If any answer is missing
+or vague, revise the draft or ask the user. Then read it as a manager deciding scope: Is the
+value clear? Can the result be observed? Are real product decisions distinguished from guesses?
+Could every clause fail independently and, if so, should it be split? Does every sentence earn
+its place? Do not create the record until the draft passes this review.
 
 Then create the proposal as a draft:
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: featureparity
 version: !ruby/object:Gem::Version
-  version: 0.0.25
+  version: 0.0.27
 platform: ruby
 authors:
 - Stowzilla
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-10-23 00:00:00.000000000 Z
+date: 2026-11-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: net-http