featureparity 0.0.26 → 0.0.28

data/lib/fp/junit.rb

@@ -756,10 +756,16 @@ module Fp
     # How a test (or group) declaration announces its name, per language. Each entry is
     # [regex, kind]; the captured group is the name. `:group` entries are describe-style
     # blocks, whose name prefixes the names of the tests inside them.
+    #
+    # A quoted name may contain its own quote escaped (`'its kind\'s logo'`), so the name
+    # runs to the first *unescaped* closing quote and is unescaped before matching — the
+    # runner reports `its kind's logo`. Stopping at the first quote cut the name off at
+    # `kind\` and the marker silently bound nothing (Fizzy #1759).
+    QUOTED_NAME = %q{((?:\\\\.|(?!\\1).)+?)\\1}
     TEST_DECL_PATTERNS = [
-      [/\b(?:it|test|bench)(?:\.\w+)*\s*\(\s*(['"`])(.+?)\1/, :test],   # vitest/jest/mocha
-      [/\bdescribe(?:\.\w+)*\s*\(\s*(['"`])(.+?)\1/, :group],           # vitest/jest/mocha group
-      [/\b(?:it|specify|scenario)\s+(['"])(.+?)\1/, :test],             # rspec
+      [/\b(?:it|test|bench)(?:\.\w+)*\s*\(\s*(['"`])#{QUOTED_NAME}/, :test],   # vitest/jest/mocha
+      [/\bdescribe(?:\.\w+)*\s*\(\s*(['"`])#{QUOTED_NAME}/, :group],           # vitest/jest/mocha group
+      [/\b(?:it|specify|scenario)\s+(['"])#{QUOTED_NAME}/, :test],             # rspec
       [/\b(?:def|fun)\s+`(.+?)`/, :test],                               # kotlin backticked
       [/\b(?:def|fun|func)\s+(test_?\w+)/i, :test]                      # minitest / xctest / pytest
     ].freeze
@@ -779,7 +785,7 @@ module Fp
           next unless match
 
           # Two-quote patterns capture the quote first, the name second.
-          return [match.captures.last, kind]
+          return [unescape_name(match.captures.last), kind]
         end
 
         # A line of real code that declares nothing recognisable: the marker doesn't
@@ -794,5 +800,9 @@ module Fp
     # the first line of real code regardless, so this only bounds how long a comment block
     # between the marker and its test may be.
     DECL_SEARCH_WINDOW = 40
+
+    def unescape_name(name)
+      name.gsub(/\\(.)/, '\\1')
+    end
   end
 end

data/lib/fp/tutorial/hexhaven/AGENTS.md

@@ -0,0 +1,5 @@
+# Hexhaven: agent notes
+
+Practice repo for the FeatureParity tutorial: a made-up board game's game server.
+Tests: `ruby -Ilib test/rules_test.rb` (prefix `JUNIT_OUT=junit.xml` for a report).
+Everything here is the `server` surface, so pin markers with `@server`.

data/lib/fp/tutorial/hexhaven/README.md

@@ -0,0 +1,29 @@
+# Hexhaven: your FeatureParity practice table
+
+Hexhaven's game server: the referee that checks every move. Rules in `lib/`, tests in
+`test/`. Plain Ruby; nothing to install.
+
+1. Run the tests:
+
+   ```sh
+   ruby -Ilib test/rules_test.rb
+   ```
+
+2. Put this above the last test in `test/rules_test.rb`, or ask your agent to
+   (`AGENTS.md` tells it how):
+
+   ```ruby
+   # fp:tallest_tower_scores_two_points@server
+   ```
+
+3. Report it:
+
+   ```sh
+   JUNIT_OUT=junit.xml ruby -Ilib test/rules_test.rb
+   fp report --junit junit.xml --repo hexhaven/server
+   ```
+
+The tallest-tower cell on Server turns from **missing** to **present**. Back to the
+tutorial.
+
+Made a mess? `fp tutorial --restart`

data/lib/fp/tutorial/hexhaven/lib/hexhaven.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+# Hexhaven — a made-up board game, and the rules its game server referees.
+#
+# Every rule here is a requirement in your FeatureParity tutorial project. The server checks
+# every move; Web, iOS and Android each show the same rules on their own, and FeatureParity
+# proves all four agree.
+module Hexhaven
+  DIE = (1..6).freeze
+  HARBOR_RATE = 3
+  TALLEST_TOWER_MINIMUM = 5
+  TALLEST_TOWER_POINTS = 2
+
+  # A turn starts with two six-sided dice.
+  def self.roll(rng = Random.new)
+    [rng.rand(DIE), rng.rand(DIE)]
+  end
+
+  # At a harbor, three of one good buy one of any other.
+  def self.harbor_trade(hand, give:, get:)
+    raise ArgumentError, "a harbor trade needs #{HARBOR_RATE} #{give}" if hand.fetch(give, 0) < HARBOR_RATE
+
+    hand.merge(give => hand[give] - HARBOR_RATE, get => hand.fetch(get, 0) + 1)
+  end
+
+  # Who holds the tallest-tower bonus, given each player's tallest tower in floors. The
+  # first tower of five floors or more takes it; only a strictly taller one steals it.
+  def self.tallest_tower(towers, holder: nil)
+    contenders = towers.select { |_, floors| floors >= TALLEST_TOWER_MINIMUM }
+    return nil if contenders.empty?
+
+    best = contenders.values.max
+    holder = nil unless holder && towers.fetch(holder, 0) == best
+    holder || contenders.key(best)
+  end
+end

data/lib/fp/tutorial/hexhaven/test/junit_reporter.rb

@@ -0,0 +1,134 @@
+# frozen_string_literal: true
+
+# A dependency-free JUnit XML reporter for Minitest, written only when JUNIT_OUT is set.
+#
+# `fp report --junit` reads the report, opens each test's file, and finds the fp:<slug>
+# marker above it. That is why every testcase carries the file and line it was declared
+# on.
+
+require 'minitest'
+require 'fileutils'
+
+module MinitestJUnitReporter
+  class Reporter < Minitest::AbstractReporter
+    def initialize(output_path, base_dir)
+      super()
+      @output_path = output_path
+      @base_dir = File.expand_path(base_dir)
+      @results = []
+    end
+
+    def record(result)
+      @results << result
+    end
+
+    def report
+      FileUtils.mkdir_p(File.dirname(@output_path))
+      File.write(@output_path, xml)
+    end
+
+    private
+
+    def xml
+      failures = @results.count { |r| r.failures.any? { |f| !f.is_a?(Minitest::Skip) } }
+      skips = @results.count { |r| r.failures.any? { |f| f.is_a?(Minitest::Skip) } }
+      time = @results.sum(&:time)
+
+      body = @results.map { |r| testcase_xml(r) }.join
+
+      <<~XML
+        <?xml version="1.0" encoding="UTF-8"?>
+        <testsuites>
+          <testsuite name="minitest" tests="#{@results.size}" failures="#{failures}" errors="0" skipped="#{skips}" time="#{format('%.6f', time)}">
+        #{body}  </testsuite>
+        </testsuites>
+      XML
+    end
+
+    def testcase_xml(result)
+      file, line = declaring_location(result)
+      attrs = [
+        %(name="#{esc(result.name)}"),
+        %(classname="#{esc(result.klass)}"),
+        %(file="#{esc(relative_to_base(file))}"),
+        # `line` is what lets `fp` bind each marker to the specific test below it. Without
+        # it fp can only handle files with exactly one marker.
+        (%(line="#{line}") if line),
+        %(time="#{format('%.6f', result.time)}")
+      ].compact.join(' ')
+
+      skip = result.failures.find { |f| f.is_a?(Minitest::Skip) }
+      real_failures = result.failures.reject { |f| f.is_a?(Minitest::Skip) }
+
+      if skip
+        %(    <testcase #{attrs}>\n      <skipped message="#{esc(skip.message)}"/>\n    </testcase>\n)
+      elsif real_failures.any?
+        inner = real_failures.map do |f|
+          tag = f.is_a?(Minitest::UnexpectedError) ? 'error' : 'failure'
+          %(      <#{tag} message="#{esc(f.message)}"/>\n)
+        end.join
+        %(    <testcase #{attrs}>\n#{inner}    </testcase>\n)
+      else
+        %(    <testcase #{attrs}/>\n)
+      end
+    end
+
+    # Where the test method is declared, as [path, line]. The path is what `fp` opens to
+    # look for markers and the line is what binds a marker to its test, so this matters
+    # more than the rest of the report.
+    def declaring_location(result)
+      # Minitest 5.18+ exposes source_location on the result.
+      return result.source_location if result.respond_to?(:source_location)
+
+      # Older minitest: ask the test class for the method's definition site.
+      klass = Object.const_get(result.klass.to_s)
+      klass.instance_method(result.name).source_location || [nil, nil]
+    rescue StandardError
+      [nil, nil]
+    end
+
+    def relative_to_base(path)
+      return '' unless path
+
+      absolute = File.expand_path(path)
+      relative = absolute.delete_prefix("#{@base_dir}/")
+      relative == absolute ? path : relative
+    rescue StandardError
+      ''
+    end
+
+    def esc(str)
+      str.to_s
+         .gsub('&', '&amp;').gsub('<', '&lt;').gsub('>', '&gt;')
+         .gsub('"', '&quot;').gsub("'", '&apos;')
+         .gsub(/[^[:print:]\t\n]/, '')
+    end
+  end
+
+  class << self
+    # Register as a Minitest plugin. Minitest calls plugin_<name>_init while building its
+    # composite reporter, which is the only point where a reporter can still be added.
+    # No-op unless JUNIT_OUT is set, so ordinary test runs are unaffected.
+    def install!
+      path = ENV['JUNIT_OUT']
+      return if path.nil? || path.strip.empty?
+      return if @installed
+
+      @installed = true
+      @output_path = File.expand_path(path)
+      @base_dir = ENV['JUNIT_BASE_DIR'] || Dir.pwd
+
+      Minitest.extensions << 'junit_xml' unless Minitest.extensions.include?('junit_xml')
+
+      Minitest.singleton_class.define_method(:plugin_junit_xml_init) do |_options|
+        Minitest.reporter << MinitestJUnitReporter.build_reporter
+      end
+    end
+
+    def build_reporter
+      Reporter.new(@output_path, @base_dir)
+    end
+  end
+end
+
+MinitestJUnitReporter.install!

data/lib/fp/tutorial/hexhaven/test/rules_test.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require_relative 'test_helper'
+
+# The referee's rules, each bound to the requirement it proves by the fp: comment directly
+# above it. `@server` pins the surface, since this repo is the game server.
+class RulesTest < Minitest::Test
+  # fp:turn_starts_with_two_dice@server
+  def test_a_turn_rolls_two_six_sided_dice
+    100.times do
+      dice = Hexhaven.roll
+      assert_equal 2, dice.size
+      dice.each { |die| assert_includes 1..6, die }
+    end
+  end
+
+  # fp:harbor_trades_three_for_one@server
+  def test_three_wool_become_one_brick_at_a_harbor
+    hand = Hexhaven.harbor_trade({ wool: 3 }, give: :wool, get: :brick)
+
+    assert_equal({ wool: 0, brick: 1 }, hand)
+  end
+
+  # fp:harbor_trades_three_for_one@server
+  def test_a_harbor_refuses_fewer_than_three
+    assert_raises(ArgumentError) { Hexhaven.harbor_trade({ wool: 2 }, give: :wool, get: :brick) }
+  end
+
+  # 👉 Your move: put this line (uncommented) above the test, or ask your agent to.
+  #      # fp:tallest_tower_scores_two_points@server
+  def test_a_six_floor_tower_takes_the_bonus_from_a_five_floor_tower
+    assert_equal :ada, Hexhaven.tallest_tower({ ada: 5, ben: 3 })
+    assert_equal :ben, Hexhaven.tallest_tower({ ada: 5, ben: 6 }, holder: :ada)
+    assert_nil Hexhaven.tallest_tower({ ada: 4, ben: 4 })
+  end
+end

data/lib/fp/tutorial/hexhaven/test/test_helper.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+require 'minitest/autorun'
+# Writes a JUnit report when JUNIT_OUT is set, which is what `fp report --junit` reads.
+require_relative 'junit_reporter'
+require_relative '../lib/hexhaven'

data/lib/fp/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Fp
-  VERSION = '0.0.26'
+  VERSION = '0.0.28'
 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:
 

data/skills/fp/references/cli.md

@@ -266,6 +266,12 @@ fp propose --project stowzilla \
 | `--required` | No | Comma-separated surfaces that must implement this |
 | `--acceptance` | No | Observable behaviour and material boundaries |
 
+After creating the draft, `fp propose` prints its quality feedback — a verdict, the issues
+found, and suggestions — in the same run (`analysis` in `--json`). Act on it: revise a weak
+draft with `fp propose-change`, or withdraw one that shouldn't be a requirement. When analysis
+is unavailable the draft is still created, and the output says the feedback couldn't be
+produced (`analysis_error`).
+
 **Write for a decision-maker, not an implementer.** The result should sound natural and be
 ready for management review without someone translating AI boilerplate or reverse-engineering
 the intended outcome. Treat it as the current record of an ongoing conversation, not a finished
@@ -370,6 +376,27 @@ 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 comments
+
+Read or join the team's conversation on a requirement, and tag people or agents in it.
+
+```bash
+fp comments print_container_qr --project stowzilla              # comments + who can be tagged
+fp comments print_container_qr --body "The label redesign dropped this — retire it?" \
+  --tag andy@example.com
+fp comments print_container_qr --body "Can you re-check this against the new label?" --tag claude
+```
+
+A comment never changes the requirement. `--tag` takes a teammate's email or name, or one of
+the team's agents by name or key name; an unknown or ambiguous tag stops the command and
+posts nothing. Tagged people get an email; each tagged agent fires the project's
+`requirement.agent_mentioned` webhook, whose payload names the agent, the requirement and
+the comment, plus the `fp` commands to read and answer it. If a human tagged you, answer
+with `fp comments <slug> --body "..."` — and if the question means the requirement is
+wrong, propose the change with `fp propose-change` rather than settling it in a comment.
+
+`fp comment` (singular) is different: it threads a comment onto an open change proposal.
+
 ### fp analyze
 
 Triage requirement quality: duplicates, fragments of a broader promise, vague wording,
@@ -459,6 +486,52 @@ classifications remain open for a human product decision. A stale candidate is r
 later fingerprint always requires a new assessment. Assessing never changes the requirement
 wording or CI outcome.
 
+### fp spot-check
+
+A random drug test for evidence. A green receipt proves a marked test ran and passed, not
+that it checks what the requirement promises. `fp spot-check` picks one active requirement
+that has evidence on record, at random, and prints its why and acceptance, its receipts, and
+the source of every `fp:<slug>` test it finds in the checkout, then a brief.
+
+```bash
+fp spot-check                         # random pick; prints the seed
+fp spot-check --seed 4821             # repeat that pick
+fp spot-check --surface cli --json    # narrow to one surface; machine-readable
+fp spot-check print_container_qr print_label   # chosen requirements, any status
+fp spot-check --count 5               # five distinct requirements at random
+fp spot-check --all                   # every active requirement with evidence
+fp spot-check --test test/qr_test.rb      # every marked test in the file
+fp spot-check --test test/qr_test.rb:42   # only the test spanning that line
+fp spot-check --path ../android       # look for the tests in another checkout
+```
+
+Use one way of choosing per run: slugs, `--count`, `--all`, or `--test` (which may be
+repeated). The seed is printed only for the random picks. In `--json` the result is
+`checks` (one entry per requirement, each with `requirement`, `evidence` and `tests`), plus
+a single `brief` that applies to every check.
+
+`--prompt` prints the whole spot check as instructions for an agent, so a person or a
+schedule can hand it over as is (`fp spot-check --count 3 --prompt | claude -p`). It ends
+with what to report for each requirement: `proves`, `does_not_prove` or `uncertain`, the
+clauses no assertion checks, the probe made and the tests that failed, and a clean
+`git status`. It can't be combined with `--json`.
+
+`--jev` first sends each requirement's marked tests (up to 10) to Jev and adds its read:
+`agree`, `gaps` or `uncertain`, how likely the tests are to cover the acceptance, the
+likeliest gap (`unasserted_clause`, `asserts_other_behaviour`, `cannot_fail`,
+`tests_a_double`), and a per-test likelihood. Treat it as a hint about where to aim the
+probe. It doesn't replace the probe. Jev is for paid plans: a person on Pro or Lifetime,
+or a project whose owner is (that is what lets an agent use it). Otherwise the spot check
+prints a note and carries on without it. Nothing Jev reads is stored.
+
+The brief: list each result and boundary the acceptance promises; name the clause each
+test's assertions actually check; make one small change to the *product code* that breaks
+the promise, run only those tests, and confirm one fails; revert and confirm `git status` is
+clean. A test that stays green under the probe, or checks something the acceptance doesn't
+say, doesn't prove the requirement. Report that to a human with what you tried. Don't
+rewrite the test or the requirement as part of a spot check. The command itself is
+read-only.
+
 #### Upgrading an existing project
 
 Changed-test auditing requires fp 0.0.17 or newer and the corresponding backend deployment.

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: featureparity
 version: !ruby/object:Gem::Version
-  version: 0.0.26
+  version: 0.0.28
 platform: ruby
 authors:
 - Stowzilla
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-10-27 00:00:00.000000000 Z
+date: 2026-11-03 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: net-http
@@ -103,6 +103,7 @@ files:
 - lib/fp/commands/check.rb
 - lib/fp/commands/ci_report.rb
 - lib/fp/commands/comment.rb
+- lib/fp/commands/comments.rb
 - lib/fp/commands/config_cmd.rb
 - lib/fp/commands/conversation.rb
 - lib/fp/commands/export.rb
@@ -121,7 +122,9 @@ files:
 - lib/fp/commands/show.rb
 - lib/fp/commands/showroom.rb
 - lib/fp/commands/showroom_media.rb
+- lib/fp/commands/spot_check.rb
 - lib/fp/commands/surfaces.rb
+- lib/fp/commands/tutorial.rb
 - lib/fp/commands/version.rb
 - lib/fp/commands/whoami.rb
 - lib/fp/config.rb
@@ -130,6 +133,12 @@ files:
 - lib/fp/parity.rb
 - lib/fp/project_config.rb
 - lib/fp/source_fingerprint.rb
+- lib/fp/tutorial/hexhaven/AGENTS.md
+- lib/fp/tutorial/hexhaven/README.md
+- lib/fp/tutorial/hexhaven/lib/hexhaven.rb
+- lib/fp/tutorial/hexhaven/test/junit_reporter.rb
+- lib/fp/tutorial/hexhaven/test/rules_test.rb
+- lib/fp/tutorial/hexhaven/test/test_helper.rb
 - lib/fp/version.rb
 - skills/fp/SKILL.md
 - skills/fp/references/cli.md