featureparity 0.0.27 → 0.0.28

data/lib/fp/commands/spot_check.rb

@@ -0,0 +1,458 @@
+# frozen_string_literal: true
+
+require 'open3'
+
+module Fp
+  module Commands
+    # `fp spot-check [<slug>...]` — a random drug test for evidence (Fizzy #1787).
+    #
+    # A green receipt says a marked test ran and passed; it doesn't say the test checks
+    # what the requirement promises. This picks requirements that claim evidence — one at
+    # random by default, or N at random, every one, the ones named, or the ones bound to a
+    # given test — puts each acceptance next to the source of its locally marked tests,
+    # and hands the agent running it a brief: match each clause to an assertion, then
+    # break the product code and confirm the tests go red.
+    #
+    # It reads and prints only. It never writes evidence and never edits a test or a
+    # requirement; what the agent finds goes to a human.
+    #
+    # `--prompt` prints the same thing as instructions to hand an agent (`| claude -p`).
+    # `--jev` first asks Jev whether the tests appear to cover each acceptance, so the agent
+    # knows where to aim the probe; Jev is for paid plans, and a 402 just means the spot
+    # check carries on without its read.
+    class SpotCheck < Base
+      # Statuses that claim a test exists and proves the requirement. `stub`, `failing`
+      # and `suspect` already say something is wrong, so there's nothing to spot-check.
+      CLAIMED_STATUSES = %w[passing pr_passing present].freeze
+
+      # The excerpt stops here even if no end of the test was found.
+      MAX_EXCERPT_LINES = 120
+      # Generated or vendored trees never hold the repo's own tests.
+      SKIP_DIRS = %w[.git node_modules vendor tmp dist build coverage .bundle].freeze
+      MAX_FILE_BYTES = 1_000_000
+
+      BRIEF = [
+        'Read the acceptance and list each observable result and boundary it promises.',
+        'For each test, name the clause its assertions actually check. A clause that no ' \
+        'assertion checks is a gap, even when the test is green.',
+        'Mutation probe: make one small change to the product code (not the test) that ' \
+        'breaks the promise, run only these tests, and confirm at least one fails. Then ' \
+        'revert it 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. Tell a human what you tried and what happened. " \
+        "Don't rewrite the test or the requirement as part of a spot check."
+      ].freeze
+
+      help_summary 'Check that requirements\' tests prove what they promise (random, chosen, or all)'
+      help_usage 'fp spot-check [<slug>...] [--count <n> | --all | --test <file>[:<line>]] ' \
+                 '[--surface <s>] [--seed <n>] [--path <dir>]'
+      help_flag :project, 'Project slug (falls back to .featureparity.yml)'
+      help_flag :count, 'Pick this many requirements at random instead of one'
+      help_flag :all, 'Check every active requirement that has evidence'
+      help_flag :test, 'Check the test(s) in this file, or the one at file:line (repeatable)'
+      help_flag :surface, 'Only pick from evidence on this surface, and only show its tests'
+      help_flag :seed, 'Random seed, to repeat a pick'
+      help_flag :path, 'Where to look for marked tests (default: the git checkout you are in)'
+      help_flag :prompt, 'Print the spot check as a prompt to hand an agent (e.g. pipe to claude -p)'
+      help_flag :jev, "Add Jev's first read of whether the tests cover each acceptance (paid plans)"
+      help_example 'fp spot-check', 'a random requirement with evidence'
+      help_example 'fp spot-check --count 5 --surface cli --json', 'five at random, for an agent on a schedule'
+      help_example 'fp spot-check print_container_qr print_label', 'chosen requirements'
+      help_example 'fp spot-check --all', 'every requirement with evidence'
+      help_example 'fp spot-check --test test/qr_test.rb:42', 'the test at that line, and its requirement'
+      help_example 'fp spot-check --count 3 --jev --prompt | claude -p', 'a scheduled run, end to end'
+      help_note 'Read-only: it records nothing and never edits a test or a requirement.'
+
+      KNOWN_FLAGS = {
+        project: :string, surface: :string, seed: :string, path: :string,
+        count: :string, all: :boolean, prompt: :boolean, jev: :boolean
+      }.freeze
+
+      # Jev reads at most this many tests per requirement (the server's cap).
+      JEV_MAX_TESTS = 10
+
+      def run(args)
+        test_refs, args = extract_repeated(args, '--test')
+        opts, slugs = parse_flags(args, KNOWN_FLAGS)
+        require_project!(opts)
+        mode = selection_mode(opts, slugs, test_refs)
+        if opts[:prompt] && output.json?
+          output.error('--prompt prints plain text for an agent; drop --json.')
+          exit 1
+        end
+        project_id = resolve_project_id(opts[:project])
+
+        seed = parse_seed(opts[:seed])
+        count = parse_count(opts[:count])
+        requirements = fetch_requirements(project_id)
+        evidence = fetch_evidence(project_id, opts[:surface])
+        root = File.expand_path(opts[:path] || repo_root(Dir.pwd))
+        tests_by_slug = find_tests(root, opts[:surface])
+
+        if mode == :test
+          tests_by_slug = select_tests(tests_by_slug, test_refs, root)
+          slugs = tests_by_slug.keys
+        end
+
+        chosen = choose(requirements, evidence, mode, slugs, count, Random.new(seed))
+        payload = {
+          'seed' => (seed if %i[random count].include?(mode)),
+          'search_root' => root,
+          'checks' => chosen.map do |requirement|
+            slug = requirement['slug']
+            {
+              'requirement' => requirement.slice('id', 'slug', 'title', 'why', 'acceptance', 'required_surfaces'),
+              'evidence' => evidence.select { |e| e['slug'] == slug },
+              'tests' => tests_by_slug.fetch(slug, [])
+            }
+          end,
+          'brief' => BRIEF
+        }.compact
+        payload['jev_note'] = add_jev_reads!(payload['checks']) if opts[:jev]
+        payload.compact!
+
+        if opts[:prompt]
+          print_prompt(payload)
+        else
+          output.success(payload) { print_report(payload) }
+        end
+      end
+
+      private
+
+      # One way of choosing per run, so it's never ambiguous what was checked.
+      def selection_mode(opts, slugs, test_refs)
+        modes = []
+        modes << :slugs unless slugs.empty?
+        modes << :all if opts[:all]
+        modes << :count if opts[:count]
+        modes << :test unless test_refs.empty?
+        if modes.length > 1
+          output.error('Choose requirements one way: slugs, --count, --all, or --test.')
+          exit 1
+        end
+
+        modes.first || :random
+      end
+
+      def parse_seed(value)
+        return Random.new_seed % 1_000_000 if value.nil?
+
+        unless value.to_s.match?(/\A\d+\z/)
+          output.error('--seed must be a whole number')
+          exit 1
+        end
+        value.to_i
+      end
+
+      def parse_count(value)
+        return 1 if value.nil?
+
+        unless value.to_s.match?(/\A[1-9]\d*\z/)
+          output.error('--count must be a whole number of at least 1')
+          exit 1
+        end
+        value.to_i
+      end
+
+      def fetch_requirements(project_id)
+        result = client.list_requirements(project_id: project_id)
+        fail_result(result) unless result[:ok]
+        result[:data]['requirements'] || []
+      end
+
+      # Every receipt the grid still believes. Rows CI has superseded are left out, so a
+      # stale `present` beside CI's verdict can't make a requirement look claimed.
+      def fetch_evidence(project_id, surface)
+        result = client.list_evidence(project_id, surface: surface)
+        fail_result(result) unless result[:ok]
+
+        superseded = Array(result[:data]['superseded_ids'])
+        (result[:data]['evidence'] || []).reject { |e| superseded.include?(e['id']) }
+      end
+
+      def choose(requirements, evidence, mode, slugs, count, rng)
+        return named(requirements, slugs) if %i[slugs test].include?(mode)
+
+        claimed = evidence.select { |e| CLAIMED_STATUSES.include?(e['status']) }.map { |e| e['slug'] }.uniq
+        # Sorted so a seed picks the same requirements however the server orders the list.
+        candidates = requirements.select { |r| r['status'] == 'active' && claimed.include?(r['slug']) }
+                                 .sort_by { |r| r['slug'] }
+        if candidates.empty?
+          output.error('No active requirement has evidence to spot-check yet.')
+          exit 1
+        end
+        return candidates if mode == :all
+
+        candidates.sample(count, random: rng).sort_by { |r| r['slug'] }
+      end
+
+      # Named requirements are checked whatever their status or evidence: asking for one
+      # is the point.
+      def named(requirements, slugs)
+        missing = slugs.reject { |slug| requirements.any? { |r| r['slug'] == slug } }
+        unless missing.empty?
+          output.error("Requirement(s) not found in project: #{missing.join(', ')}")
+          exit 1
+        end
+
+        slugs.uniq.map { |slug| requirements.find { |r| r['slug'] == slug } }
+      end
+
+      # Keep only the marked tests a --test reference names: every one in the file, or with
+      # a line, the one whose marker-to-end span holds it.
+      def select_tests(tests_by_slug, refs, root)
+        wanted = refs.map { |ref| parse_test_ref(ref, root) }
+        selected = tests_by_slug.transform_values do |tests|
+          tests.select do |t|
+            wanted.any? { |file, line| t['file'] == file && (line.nil? || (t['line']..t['end_line']).cover?(line)) }
+          end
+        end.reject { |_, tests| tests.empty? }
+
+        if selected.empty?
+          output.error("No fp: marked test found at #{refs.join(', ')} under #{root}.")
+          exit 1
+        end
+        selected
+      end
+
+      # `path[:line]`, with the path taken relative to the working directory or to root.
+      def parse_test_ref(ref, root)
+        path, line = ref.match(/\A(.+?)(?::(\d+))?\z/).captures
+        absolute = File.expand_path(path)
+        file = if absolute.start_with?("#{root}/")
+                 absolute.delete_prefix("#{root}/")
+               else
+                 path.delete_prefix('./')
+               end
+        [file, line&.to_i]
+      end
+
+      # Ask Jev about each check that has tests here, adding `jev` to it. Stops at the first
+      # refusal (unpaid, unconfigured, unreachable): the answer would be the same for the
+      # rest, and the spot check stands without it. Returns a note when it stopped.
+      def add_jev_reads!(checks)
+        checks.each do |check|
+          tests = check['tests'].first(JEV_MAX_TESTS)
+                                .map { |t| t.slice('file', 'line', 'title', 'source') }
+          next if tests.empty?
+
+          result = client.review_spot_check_tests(check['requirement']['id'], tests)
+          return jev_refusal(result) unless result[:ok]
+
+          check['jev'] = result[:data]['review']
+        end
+        nil
+      end
+
+      def jev_refusal(result)
+        case result[:status]
+        when 402 then "Jev's read is for paid plans, so this spot check runs without it. (#{result[:error]})"
+        else "Jev couldn't read the tests, so this spot check runs without it: #{result[:error]}"
+        end
+      end
+
+      def repo_root(dir)
+        out, status = Open3.capture2('git', '-C', dir, 'rev-parse', '--show-toplevel', err: File::NULL)
+        status.success? ? out.strip : dir
+      rescue SystemCallError
+        dir
+      end
+
+      # Every fp:<slug> marker under root with the test it annotates, grouped by slug.
+      # One pass over the tree, however many requirements are being checked.
+      def find_tests(root, surface)
+        tests = Hash.new { |h, k| h[k] = [] }
+        source_files(root).each do |rel|
+          contents = read_text(File.join(root, rel))
+          next unless contents&.include?('fp:')
+
+          lines = contents.lines
+          JUnit.scan_markers(contents).each do |marker|
+            next if surface && !marker[:surfaces].empty? && !marker[:surfaces].include?(surface)
+
+            source, truncated = excerpt(lines, marker[:line] - 1)
+            tests[marker[:slug]] << {
+              'file' => rel,
+              'line' => marker[:line],
+              'end_line' => marker[:line] + source.lines.length - 1,
+              'title' => marker[:title],
+              'surfaces' => marker[:surfaces],
+              'test_type' => marker[:test_type],
+              'source' => source,
+              'truncated' => truncated
+            }
+          end
+        end
+        tests
+      end
+
+      # Tracked files when root is in a git checkout (so .gitignore is respected),
+      # otherwise a walk of the tree.
+      def source_files(root)
+        out, status = Open3.capture2('git', '-C', root, 'ls-files', '-z', err: File::NULL)
+        files = status.success? ? out.split("\0") : walk(root)
+        files.reject { |f| f.split('/').any? { |part| SKIP_DIRS.include?(part) } }.sort
+      rescue SystemCallError
+        walk(root).sort
+      end
+
+      def walk(root)
+        Dir.glob('**/*', base: root).select { |f| File.file?(File.join(root, f)) }
+      end
+
+      def read_text(path)
+        return nil unless File.file?(path) && File.size(path) <= MAX_FILE_BYTES
+
+        contents = File.read(path, mode: 'rb')
+        return nil if contents.include?("\0")
+
+        contents.force_encoding(Encoding::UTF_8).scrub
+      rescue SystemCallError
+        nil
+      end
+
+      # The marker line through the end of the test below it. The end is the first line
+      # back at the declaration's indent: kept when it closes the block (`end`, `}`, `})`),
+      # dropped when it starts the next thing (Python, or the next test).
+      def excerpt(lines, marker_idx)
+        decl_idx = declaration_index(lines, marker_idx)
+        return [lines[marker_idx, 10].join, false] unless decl_idx
+
+        indent = indent_of(lines[decl_idx])
+        last = decl_idx
+        truncated = true
+        ((decl_idx + 1)...lines.length).each do |i|
+          break if i - marker_idx >= MAX_EXCERPT_LINES
+
+          line = lines[i]
+          if line.strip.empty? || indent_of(line) > indent
+            last = i
+            next
+          end
+
+          last = i if line.strip.match?(/\A(?:end\b|[}\])])/)
+          truncated = false
+          break
+        end
+        truncated = false if last == lines.length - 1
+
+        [lines[marker_idx..last].join.rstrip + "\n", truncated]
+      end
+
+      # The test's declaration: the first line of code below the marker, past any further
+      # comments and annotations (`@Test`).
+      def declaration_index(lines, marker_idx)
+        ((marker_idx + 1)...[marker_idx + 1 + JUnit::DECL_SEARCH_WINDOW, lines.length].min).find do |i|
+          line = lines[i]
+          !(line.strip.empty? || line.match?(JUnit::COMMENT_LINE_RE) || line.match?(/\A\s*@\w/))
+        end
+      end
+
+      def indent_of(line)
+        line[/\A[ \t]*/].length
+      end
+
+      def print_report(payload)
+        checks = payload['checks']
+        if payload['seed']
+          puts "Picked at random (seed #{payload['seed']}; repeat with --seed #{payload['seed']})"
+        end
+        puts "Spot-checking #{checks.length} requirements." if checks.length > 1
+        checks.each { |check| print_check(check, payload['search_root']) }
+
+        puts "Note: #{payload['jev_note']}" if payload['jev_note']
+        puts 'Your brief, for each requirement:'
+        payload['brief'].each_with_index { |step, i| puts "  #{i + 1}. #{step}" }
+      end
+
+      # The spot check as instructions for an agent working in this checkout: who it is,
+      # what to do for each requirement, the dossier, and the shape of the report back.
+      def print_prompt(payload)
+        checks = payload['checks']
+        # On stderr, so a pipe into an agent carries only the prompt.
+        warn "Note: #{payload['jev_note']}" if payload['jev_note']
+        puts "You are spot-checking #{checks.length == 1 ? 'one requirement' : "#{checks.length} requirements"} " \
+             "in the checkout at #{payload['search_root']}: do the tests bound to it actually prove what it " \
+             'promises? A green test only shows that it ran and passed.'
+        puts
+        puts 'For each requirement below:'
+        payload['brief'].each_with_index { |step, i| puts "#{i + 1}. #{step}" }
+        puts
+        puts 'Run tests with whatever this repository uses. Change only product code, one probe at a time, ' \
+             'and revert each probe before the next. If a requirement has no tests here, say so and move on.'
+        puts "Jev's read, where given, is a hint about where to aim the probe, not a verdict." if checks.any? { |c| c['jev'] }
+        checks.each { |check| print_check(check, payload['search_root']) }
+        puts 'When you are done, report for each requirement:'
+        puts '- slug, and a verdict: proves, does_not_prove, or uncertain'
+        puts '- each acceptance clause with no assertion that checks it'
+        puts '- the probe you made (file and change), the tests you ran, and which failed'
+        puts '- confirmation that `git status` is clean'
+      end
+
+      def print_check(check, search_root)
+        req = check['requirement']
+        puts
+        puts "Spot check: #{req['slug']}"
+        puts "  #{req['title']}"
+        puts
+        puts "Why:        #{req['why']}" if req['why'].to_s.strip != ''
+        puts 'Acceptance:'
+        req['acceptance'].to_s.each_line { |l| puts "  #{l.rstrip}" }
+        puts
+
+        puts 'Evidence on record:'
+        if check['evidence'].empty?
+          puts '  (none)'
+        else
+          check['evidence'].each do |e|
+            location = [e['source_file'], e['source_line']].compact.join(':')
+            puts "  #{e['surface']}  #{e['status']}  #{location}".rstrip
+          end
+        end
+        puts
+
+        tests = check['tests']
+        if tests.empty?
+          puts "No fp:#{req['slug']} marker found under #{search_root}."
+          puts 'The tests may live in another repo: run this from that checkout or pass --path.'
+          puts 'If they should be here, the marker is gone, and that is the finding.'
+        else
+          puts "#{tests.length} marked test(s) under #{search_root}:"
+          tests.each do |t|
+            puts
+            puts "--- #{t['file']}:#{t['line']}#{"  (#{t['title']})" if t['title']}"
+            puts t['source']
+            puts '    … (cut off; read the rest in the file)' if t['truncated']
+          end
+        end
+        puts
+        print_jev(check['jev']) if check['jev']
+      end
+
+      def print_jev(review)
+        covers = review['covers_acceptance'] || {}
+        puts "Jev's first read: #{review['verdict']}" \
+             "#{" (covers the acceptance: #{percent(covers['probability'])}, confidence #{percent(covers['confidence'])})" if covers['probability']}"
+        gap = review['primary_gap']
+        puts "  Likeliest gap: #{gap['description']}" if gap
+        Array(review['tests']).each do |t|
+          read = t['checks_promise'] || {}
+          next unless read['probability']
+
+          puts "  #{t['file']}:#{t['line']} checks the promise: #{percent(read['probability'])}"
+        end
+        puts
+      end
+
+      def percent(value)
+        "#{(value.to_f * 100).round}%"
+      end
+
+      def fail_result(result)
+        output.error(result[:error], status: result[:status])
+        exit 1
+      end
+    end
+  end
+end

data/lib/fp/commands/tutorial.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+require 'fileutils'
+
+module Fp
+  module Commands
+    # fp tutorial [--dir PATH]
+    #
+    # Deals the newcomer a practice table (Fizzy #1446): Hexhaven, the made-up board game
+    # their tutorial project tracks, as a tiny repository whose tests run on Ruby alone.
+    # Two rules are already bound by fp: markers; the tallest-tower test is not, and the
+    # web tutorial's "Deal yourself in" step asks the reader to mark it and run
+    # `fp report`, which turns that Server cell in their sample matrix from missing to
+    # present. The rule slugs must match lambda/lib/tutorial_project.rb.
+    #
+    # Makes no API calls, like `fp init`: the files are the same for everyone, and the
+    # project slug is the tutorial's fixed one.
+    class Tutorial < Base
+      help_summary 'Write Hexhaven, a sample repo to practise marking and reporting tests'
+      help_usage 'fp tutorial [--dir PATH] [--restart]'
+      help_flag :dir, 'Where to write it (defaults to ./hexhaven)'
+      help_flag :restart, 'Replace an existing Hexhaven checkout with a fresh one'
+      help_example 'fp tutorial'
+      help_example 'fp tutorial --dir ~/code/hexhaven'
+      help_example 'fp tutorial --restart', 'Start the practice repo over, markers and all'
+      help_note "Pairs with the Tutorial in the web app, which opens your sample project.\n" \
+                'Makes no API calls. Only --restart replaces a directory, and only a Hexhaven one.'
+
+      KNOWN_FLAGS = { dir: :string, restart: :boolean }.freeze
+      TEMPLATE_DIR = File.expand_path('../tutorial/hexhaven', __dir__)
+      PROJECT_SLUG = 'fp-tutorial'
+      SURFACE = 'server'
+
+      def run(args)
+        opts, = parse_flags(args, KNOWN_FLAGS)
+        target = File.expand_path(opts[:dir] || 'hexhaven')
+
+        if File.exist?(target) && !(File.directory?(target) && Dir.empty?(target))
+          unless hexhaven?(target)
+            output.error("#{target} already exists and isn't a Hexhaven checkout. Pick another place with --dir.")
+            exit 1
+          end
+          unless opts[:restart]
+            output.error("#{target} already has Hexhaven in it. Run `fp tutorial --restart` to start it over.")
+            exit 1
+          end
+          FileUtils.rm_rf(target)
+        end
+
+        written = write_repo(target)
+
+        output.success({ dir: target, files: written }) do
+          puts "Dealt Hexhaven into #{target}"
+          puts
+          puts '  cd ' + display_path(target)
+          puts '  ruby -Ilib test/rules_test.rb'
+          puts
+          puts 'Then follow README.md.'
+        end
+      end
+
+      private
+
+      def write_repo(target)
+        FileUtils.mkdir_p(target)
+        files = Dir.glob('**/*', base: TEMPLATE_DIR).reject { |f| File.directory?(File.join(TEMPLATE_DIR, f)) }
+        files.each do |relative|
+          dest = File.join(target, relative)
+          FileUtils.mkdir_p(File.dirname(dest))
+          FileUtils.cp(File.join(TEMPLATE_DIR, relative), dest)
+        end
+        # Dotfiles stay out of the gem's file list, so they're written here instead.
+        File.write(File.join(target, ProjectConfig::FILENAME),
+                   ProjectConfig.render(project: PROJECT_SLUG, surface: SURFACE))
+        File.write(File.join(target, '.gitignore'), "junit.xml\n")
+        # The agent brief is the one `fp init` writes, appended to the template's short
+        # Hexhaven intro, so "ask your agent to bind the test" works and stays current.
+        Init.write_agent_docs!(target, PROJECT_SLUG)
+        (files + [ProjectConfig::FILENAME, '.gitignore']).uniq.sort
+      end
+
+      # Only a directory this command wrote may be replaced: one whose project config
+      # names the tutorial project.
+      def hexhaven?(target)
+        config = File.join(target, ProjectConfig::FILENAME)
+        File.file?(config) && ProjectConfig.parse(config)['project'] == PROJECT_SLUG
+      end
+
+      def display_path(target)
+        relative = target.delete_prefix("#{Dir.pwd}/")
+        relative == target ? target : relative
+      end
+    end
+  end
+end

data/lib/fp/commands/whoami.rb

@@ -32,6 +32,8 @@ module Fp
             puts
             puts "  ⚠ Profile is tagged for environment '#{r[:profile_environment]}' " \
                  "but the resolved API URL points at '#{r[:environment]}'."
+            puts "    A key only works in the environment that minted it. Mint one in the " \
+                 "'#{r[:environment]}' web app (Account → Agents & API keys) and use it there."
           end
 
           unless r[:authenticated]

data/lib/fp/commands.rb

@@ -10,14 +10,17 @@ require_relative 'commands/show'
 require_relative 'commands/propose'
 require_relative 'commands/propose_change'
 require_relative 'commands/comment'
+require_relative 'commands/comments'
 require_relative 'commands/history'
 require_relative 'commands/analyze'
 require_relative 'commands/changes'
 require_relative 'commands/report'
 require_relative 'commands/ci_report'
 require_relative 'commands/changed_tests'
+require_relative 'commands/spot_check'
 require_relative 'commands/check'
 require_relative 'commands/init'
+require_relative 'commands/tutorial'
 require_relative 'commands/matrix'
 require_relative 'commands/export'
 require_relative 'commands/profile'

data/lib/fp/config.rb

@@ -63,6 +63,18 @@ module Fp
       self.class.environment_for(@api_url)
     end
 
+    # Said when a call comes back empty and the active profile was made for another
+    # environment: its key belongs to that environment and reaches nothing here.
+    def environment_mismatch_hint
+      tagged = profile_environment
+      here = environment
+      return nil if tagged.nil? || here.nil? || tagged == here
+
+      "Your profile '#{@profile_name}' holds a key for '#{tagged}', but fp is talking to '#{here}'. " \
+        "A key only works in the environment that minted it: mint one in the '#{here}' web app " \
+        "(Account → Agents & API keys), or unset FP_API_URL to go back to '#{tagged}'."
+    end
+
     # The environment explicitly recorded on the active profile, if any.
     # Falls back to nil when unset (callers derive from api_url instead).
     def profile_environment

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`