featureparity 0.0.27 → 0.0.28

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.27'
+  VERSION = '0.0.28'
 end

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.27
+  version: 0.0.28
 platform: ruby
 authors:
 - Stowzilla
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-11-02 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