featureparity 0.0.27 → 0.0.29

data/lib/fp/commands/init.rb

@@ -24,8 +24,10 @@ module Fp
     # marker comment on re-run.
     class Init < Base
       help_summary 'Onboard a repo: write .featureparity.yml, a CI gate workflow, and agent docs'
-      help_usage 'fp init --project <slug> [--surface X] [--level L] [--dir PATH] [--force]'
+      help_usage 'fp init --project <slug> [--surface X] [--level L] [--dir PATH] [--force]',
+                 'fp init --detect [--dir PATH] [--json]'
       help_flag :project, 'Project slug to record in .featureparity.yml', required: true
+      help_flag :detect, 'Suggest a slug, surfaces and test-report commands from the repo; writes nothing'
       help_flag :surface, 'Default surface for this (single-surface) repo'
       help_flag :level, 'Enforcement level to record (usually omit and let the project decide)'
       help_flag :dir, 'Target directory (defaults to the working directory)'
@@ -34,7 +36,9 @@ module Fp
       help_flag :no_agents, 'Skip appending the AGENTS.md section'
       help_example 'fp init --project stowzilla --surface api'
       help_example 'fp init --project stowzilla --no-workflow'
-      help_note 'Makes no API calls, so a repo can be onboarded before anyone has a key.'
+      help_example 'fp init --detect', 'See what fp makes of this repo before choosing a slug and surfaces'
+      help_note "Makes no API calls, so a repo can be onboarded before anyone has a key.\n" \
+                'Committing the workflow before the FP_API_KEY secret exists is fine: the gate skips with an explanation.'
 
       KNOWN_FLAGS = {
         project: :string,
@@ -43,7 +47,8 @@ module Fp
         dir: :string,
         force: :boolean,
         no_workflow: :boolean,
-        no_agents: :boolean
+        no_agents: :boolean,
+        detect: :boolean
       }.freeze
 
       WORKFLOW_PATH = File.join('.github', 'workflows', 'feature-parity.yml')
@@ -56,6 +61,17 @@ module Fp
       AGENTS_MARKER = '<!-- feature-parity:begin -->'
       AGENTS_END_MARKER = '<!-- feature-parity:end -->'
 
+      # The version line under the section's heading, so `fp doctor` (and a reader) can tell
+      # which fp wrote it. Kept out of AGENTS_MARKER so sections written before the stamp
+      # are still recognised as ours.
+      AGENTS_VERSION_RE = /Written by fp (\d+\.\d+\.\d+[\w.-]*)/
+
+      # The guidance the skill and this section share lives once, in the skill, between
+      # `<!-- fp-shared:begin NAME -->` / `<!-- fp-shared:end NAME -->`, and is copied in
+      # here (Fizzy #1786). Two hand-kept copies had drifted, and an agent with both the
+      # skill and AGENTS.md read the same pages twice.
+      SKILL_PATH = File.expand_path('../../../skills/fp/SKILL.md', __dir__)
+
       def run(args)
         opts, = parse_flags(args, KNOWN_FLAGS)
 
@@ -65,6 +81,8 @@ module Fp
           exit 1
         end
 
+        return print_detection(RepoDetector.new(root).detect) if opts[:detect]
+
         existing = ProjectConfig.discover(root)
         project_slug = opts[:project] || existing.project
         unless project_slug
@@ -80,6 +98,7 @@ module Fp
 
         written = []
         skipped = []
+        @detection = RepoDetector.new(root).detect
 
         write_project_config(root, project_slug, level, opts, written, skipped)
         write_workflow(root, opts, written, skipped) unless opts[:no_workflow]
@@ -88,8 +107,47 @@ module Fp
         report(project_slug, root, written, skipped, opts)
       end
 
+      # The same agent brief `fp init` writes, for another command to put in a repo it
+      # creates (`fp tutorial`'s Hexhaven), so the two can never drift apart. Appends to
+      # an existing AGENTS.md/CLAUDE.md the way init does. Returns the paths written.
+      def self.write_agent_docs!(root, project_slug)
+        written = []
+        new.send(:write_agent_docs, root, project_slug, { dir: root }, written, [])
+        written.map(&:first)
+      end
+
+      # One shared block from the skill, markers included. A gem missing its skill (it
+      # ships in spec.files, so only a broken install) still gets a pointer, not a crash.
+      def self.shared_guidance(name)
+        @shared_guidance ||= {}
+        @shared_guidance[name] ||= begin
+          text = File.read(SKILL_PATH)
+          pattern = /<!-- fp-shared:begin #{Regexp.escape(name)} -->.*?<!-- fp-shared:end #{Regexp.escape(name)} -->/m
+          text[pattern] || "See the `fp` agent skill (#{name})."
+        rescue SystemCallError
+          "See the `fp` agent skill bundled with the featureparity gem (#{name})."
+        end
+      end
+
       private
 
+      def shared_guidance(name)
+        self.class.shared_guidance(name)
+      end
+
+      # `fp init --detect`: what the repo looks like, nothing written.
+      def print_detection(detection)
+        output.success(detection) do
+          RepoDetector.print_summary(detection)
+          puts
+          puts 'Nothing was written. To onboard with these suggestions:'
+          keys = detection['surfaces'].map { |s| s['key'] }
+          surfaces = keys.empty? ? '<keys>' : keys.join(',')
+          puts "  fp projects create #{detection['slug']} --name \"...\" --surfaces #{surfaces}   # if it doesn't exist yet"
+          puts "  fp init --project #{detection['slug']}#{keys.length == 1 ? " --surface #{keys.first}" : ''}"
+        end
+      end
+
       def write_project_config(root, project_slug, level, opts, written, skipped)
         path = File.join(root, ProjectConfig::FILENAME)
         body = ProjectConfig.render(
@@ -187,8 +245,11 @@ module Fp
           puts '  2. Add the FP_API_KEY secret to the repo so CI can report evidence and run the gate.'
           puts "  3. Try the gate locally:  fp check#{opts[:surface] ? " --surface #{opts[:surface]}" : ''}"
           puts
-          puts 'Until the FP_API_KEY secret is added, the gate skips with an explanation'
-          puts 'instead of failing — so the first push that onboards the repo stays green.'
+          puts 'Commit these files now, even before the FP_API_KEY secret exists: until it is'
+          puts 'added, the gate skips with an explanation instead of failing, so the first push'
+          puts 'that onboards the repo stays green.'
+          puts
+          print_test_guidance
           puts
           puts 'The gate starts at the `regression` level, which only fails on tests that have'
           puts 'gone red — it will not block you on requirements that were never covered. Raise'
@@ -196,10 +257,100 @@ module Fp
         end
       end
 
+      # The detected test-report command(s) and the database note, so the first report
+      # doesn't start with working out how to get a report out of the suite.
+      def print_test_guidance
+        detection = @detection || {}
+        runners = detection['test_runners'] || []
+        if runners.empty?
+          puts 'No test runner recognised. Any runner that writes JUnit XML works: fp report --junit <file>.'
+        else
+          puts 'To report evidence from your tests:'
+          runners.each do |r|
+            puts "  #{r['name']}: #{r['fp_run'] || r['report_command']}"
+            puts "    or write the report yourself: #{r['report_command']}" if r['fp_run']
+            puts "    needs #{r['dependency']}" if r['dependency']
+          end
+        end
+        note = RepoDetector.database_note(detection['database'])
+        if note
+          puts
+          puts note
+          puts "A devcontainer is at #{detection['devcontainer']} and may provide it locally." if detection['devcontainer']
+        end
+        puts
+        puts 'Run `fp doctor` any time to check fp, its config and this repo.'
+      end
+
+      # A commented-out service for the report job when the tests need a database server,
+      # since the recipe can't run them without one.
+      DATABASE_SERVICES = {
+        'postgresql' => <<~YAML,
+          #   services:
+          #     postgres:
+          #       image: postgres:16
+          #       env:
+          #         POSTGRES_PASSWORD: postgres
+          #       ports: ['5432:5432']
+          #       options: >-
+          #         --health-cmd pg_isready --health-interval 10s --health-timeout 5s --health-retries 5
+        YAML
+        'mysql' => <<~YAML,
+          #   services:
+          #     mysql:
+          #       image: mysql:8
+          #       env:
+          #         MYSQL_ROOT_PASSWORD: root
+          #       ports: ['3306:3306']
+          #       options: >-
+          #         --health-cmd "mysqladmin ping" --health-interval 10s --health-timeout 5s --health-retries 5
+        YAML
+        'mongodb' => <<~YAML
+          #   services:
+          #     mongodb:
+          #       image: mongo:7
+          #       ports: ['27017:27017']
+        YAML
+      }.freeze
+
+      def database_lines
+        db = (@detection || {})['database']
+        return '' unless db && db['needed']
+
+        kinds = db['kinds'] & RepoDetector::SERVER_DATABASES
+        services = kinds.filter_map { |k| DATABASE_SERVICES[k] }.first.to_s
+        indent = '  '
+        lines = ["#   # TODO: the tests need #{kinds.join('/')} (#{db['evidence'].first(3).join('; ')}).",
+                 '#   # This job has no database service: uncomment and adapt the one below, and point',
+                 '#   # the app at it (e.g. DATABASE_URL), or the suite cannot run here.']
+        (lines + services.lines.map(&:chomp)).map { |l| "#{indent}#{l}\n" }.join
+      end
+
+      def test_command_line
+        runner = ((@detection || {})['test_runners'] || []).first
+        return 'echo "replace with your test command emitting junit.xml"' unless runner
+
+        runner['report_command']
+      end
+
+      def report_file
+        runner = ((@detection || {})['test_runners'] || []).first
+        runner && !runner['report_file'].to_s.end_with?('test-results') ? runner['report_file'] : 'junit.xml'
+      end
+
       # The CI gate and its adaptable reporting recipe are separate concerns: the gate
       # blocks pull requests, while reporting needs a trusted context with FP_API_KEY and
       # should cover both pull requests and default-branch pushes.
+      #
+      # The recipe's test step uses the report command detected for this repo, and when the
+      # tests need a database server a commented-out service goes in ahead of its steps.
       def workflow_body
+        body = workflow_template
+        db = database_lines
+        db.empty? ? body : body.sub("  #   steps:\n", "#{db}  #   steps:\n")
+      end
+
+      def workflow_template
         <<~YAML
           # FeatureParity — parity enforcement.
           #
@@ -341,7 +492,7 @@ module Fp
             #   steps:
             #     - uses: actions/checkout@v4
             #     - name: Run tests (emit JUnit)
-            #       run: echo "replace with your test command emitting junit.xml"
+            #       run: #{test_command_line}
             #     - name: Report to FeatureParity
             #       if: always() && env.HAVE_FP_KEY == 'true'
             #       env:
@@ -349,7 +500,7 @@ module Fp
             #       run: |
             #         gem install featureparity
             #         args=(
-            #           --junit junit.xml
+            #           --junit #{report_file}
             #           --surface <surface-key>
             #           --ci-url "${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}"
             #         )
@@ -368,6 +519,10 @@ module Fp
           #{AGENTS_MARKER}
           ## FeatureParity (this project tracks feature parity)
 
+          _Written by fp #{Fp::VERSION} (`fp init`). `fp init --force` refreshes it, and `fp doctor`
+          says when the installed fp is newer. The blocks between `fp-shared` comments are the
+          `fp` agent skill's own text: if you have the skill loaded, you've read them already._
+
           This repo is tracked by [FeatureParity](https://featureparity.dev) as project
           **`#{project_slug}`** (see `.featureparity.yml`). Requirements are shared across every
           surface the product ships on, and CI enforces that they stay covered — a pull request
@@ -379,6 +534,9 @@ module Fp
           2. **The requirements stay true.** If none covers what you're building, propose one.
              If one is wrong or outdated, propose the change — never edit or ignore it.
 
+          **First run in this repo?** The loop below assumes the catalog already describes the
+          product. If it doesn't yet, follow *Onboarding a repo* near the end of this section first.
+
           **Start every task by checking the requirements — before you write code, not
           after.** When you pick up a feature or bug, first inventory the full request and
           compare it with the active and draft requirements. Find what already covers the work,
@@ -396,66 +554,7 @@ module Fp
           fp changes --source-url URL   # requirement activity prompted by a work item
           ```
 
-          **The requirement catalog is the human-readable product specification, not a box to
-          tick with one umbrella record.** It records the team's current shared understanding;
-          it is not a finished decree handed from product to engineering. Refine requirements
-          through ongoing conversation with customers, domain experts, and builders. The human
-          product owner decides value and priority; agents should surface gaps, inconsistencies,
-          alternatives, and useful splits rather than silently making product decisions.
-
-          Before coding, enumerate the independently meaningful promises in the request:
-          user-visible behaviours, policies, limits, plans, deadlines, state transitions,
-          permissions, failure modes, and affected surfaces. Then model them:
-
-          - Give each independently testable or independently failable product promise its own
-            focused requirement. If one acceptance sentence joins behaviours that could pass or
-            fail separately, split it.
-          - Use a parent for the broad capability and children for distinct behaviours, policies,
-            or surface-specific promises. Do not create requirements for implementation details
-            or refactors that make no product promise.
-          - Put concrete product decisions — prices, quotas, dates, roles, fallbacks — in the
-            requirement acceptance criteria. Never leave them only as assumptions in code or a PR.
-          - Check adjacent requirements and their history. New requirements do not excuse an old
-            requirement that the work makes inaccurate; propose a change to keep the whole catalog true.
-          - Before finishing, reconcile the implementation against the catalog: every shipped
-            behaviour maps to a current requirement, every changed promise is recorded, and every
-            focused requirement has appropriate marked evidence or an explicit gap. A broad marker
-            must never appear to prove several acceptance clauses that its test does not exercise.
-
-          **Prevent contradictions before they enter the catalog.** Before proposing a new or changed
-          promise, compare its intended acceptance criteria with related active and draft requirements
-          and read their history. Ask whether both promises can be true at the same time for the same
-          user, state, and conditions. If not, do not add another requirement.
-
-          A failing test bound to an existing requirement, or an implementation that only works by
-          changing one, is a contradiction signal — not permission to weaken the test or write a
-          second requirement around it. Identify which promise matches product intent, then use
-          `fp propose-change` (or `--removal`) with the source and reason to put that decision before
-          a human. If the intent is unclear, stop and ask rather than making the catalog say both things.
-
-          **Treat existing tests as protected product evidence.** Before editing an existing test,
-          determine what expectation it already records and whether CI has passing evidence for it.
-
-          - If the test backs passing evidence, do not rewrite it to make the current implementation
-            or a new requirement fit. Explicitly flag the intended test edit in the work item and pull
-            request. If its expected behaviour would change, propose the requirement change and wait
-            for explicit human approval before editing the test; a newly green run must not hide that
-            the proof itself changed.
-          - When FeatureParity reports a changed bound test, run `fp changed-tests` (or add `--json`)
-            and compare the accepted and candidate source revisions with the requirement. Record the
-            exact candidate through `fp changed-tests assess <id> --candidate-fingerprint <sha256>`
-            with a plain-language explanation and one classification: `still_proves`,
-            `no_longer_proves`, or `uncertain`. The first resolves only that fingerprint; the others
-            remain open for a human product decision. A later fingerprint needs a new assessment.
-          - A new requirement does not retroactively own or supersede a pre-existing failing test —
-            whether the requirement is draft or active. Do not change that test, or adopt it as the new
-            requirement's proof, merely to make the new work pass. Surface the conflict and wait for
-            explicit human approval to change the existing expectation.
-
-          A changed-test finding is an audit signal alongside the testcase's independent CI outcome.
-          It is not a failed test and is separate from `suspect`, which means requirement wording
-          changed and its evidence needs re-verification. Neither permits rewriting a test before
-          product intent is decided.
+          #{shared_guidance('modeling')}
 
           If no requirement covers what you're building, propose one or a parent/child tree. Agents
           always create **drafts**; a human activates them:
@@ -466,56 +565,7 @@ module Fp
             --source-type fizzy --source-url <card-or-issue-url>
           ```
 
-          **Write a requirement as a product decision someone can approve, not as a design
-          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, 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.
-          - **Implementation detail:** leave out components, data models, algorithms, endpoints,
-            and UI controls unless that interface or constraint is itself part of the promise.
-
-          Learn from the request, existing requirements and history, and available evidence about
-          what users actually do. Look for what they attempt, where they abandon a task, what they
-          use, and what experiments reveal. Treat the first proposed solution as input, not
-          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.`
-          - ❌ **Title:** `Implement Redis-backed 30-second status polling`
-            **Why:** `This important feature ensures a seamless, robust experience.`
-            **Acceptance:** `Use a background worker and refresh every 30 seconds.`
-            This invents policy, prescribes a design, and never states the product outcome.
-
-          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.
+          #{shared_guidance('writing')}
 
           ### 2. If the requirement is wrong, propose a change — don't silently edit it
 
@@ -570,6 +620,10 @@ module Fp
             --work-item <card-or-issue-url>
           ```
 
+          `--junit` also takes RSpec's own `--format json` report. To run the suite and report in
+          one step with no formatter added to the project (rspec, pytest, vitest, playwright):
+          `fp run --surface <surface> --repo <org/repo> -- <test command>`.
+
           Report `present` or `stub` only — **never** claim `passing`/`failing`. Those are CI's
           to write, via `fp ci-report`, and the gate trusts them precisely because agents can't
           set them.
@@ -577,6 +631,8 @@ module Fp
           If you just changed a requirement's wording and re-wrote its tests, re-report the
           evidence: that's what clears `suspect`.
 
+          #{shared_guidance('media')}
+
           ### 5. Confirm you didn't break the gate
 
           ```bash
@@ -585,6 +641,14 @@ module Fp
 
           `fp check --json` if you want to parse the violations. Run `fp help` for the full
           command list.
+
+          ### Onboarding a repo (first run)
+
+          #{shared_guidance('onboarding')}
+
+          ### Troubleshooting
+
+          #{shared_guidance('troubleshooting')}
           #{AGENTS_END_MARKER}
         MARKDOWN
       end

data/lib/fp/commands/list.rb

@@ -16,6 +16,7 @@ module Fp
       help_example 'fp list --project stowzilla'
       help_example 'fp list --project stowzilla --status draft', 'Drafts are hidden by default'
       help_example 'fp list --project stowzilla --gaps --surface customer_android'
+      help_example 'fp list --status draft --gaps', 'Drafts lacking evidence on a required surface'
 
       KNOWN_FLAGS = {
         project: :string,
@@ -36,7 +37,9 @@ module Fp
         # rather than passing --surface on every call.
         opts[:surface] ||= project_config.surface
 
-        if opts[:gaps]
+        if opts[:gaps] && opts[:status] == 'draft'
+          list_draft_gaps(project_id, opts)
+        elsif opts[:gaps]
           list_gaps(project_id, opts)
         else
           list_requirements(project_id, opts)
@@ -191,7 +194,44 @@ module Fp
         render_gaps(gaps, report, opts)
       end
 
-      def render_gaps(gaps, report, opts)
+      # Draft gaps: `--status draft --gaps`. The gate doesn't measure never-approved
+      # drafts, so the plain gaps read above can't see them and this used to print "No
+      # gaps found" on a project whose every requirement was an untested draft (Fizzy
+      # #1786). The parity report's `drafts` section resolves each draft's cells from
+      # evidence the way the grid would; a gap here is the same thing it is above — a
+      # cell in a state that violates at `covered` (missing, stub, failing) — read from
+      # the report's own violating_states rather than decided here. Informational: drafts
+      # never fail a gate.
+      def list_draft_gaps(project_id, opts)
+        result = client.get_parity_with_drafts(project_id, level: 'covered', surface: opts[:surface])
+
+        unless result[:ok]
+          output.error(result[:error], status: result[:status])
+          exit 1
+        end
+
+        report = result[:data]['parity'] || {}
+        unless report.key?('drafts')
+          output.error('This FeatureParity API does not report draft coverage yet (it predates ' \
+                       '`include_drafts`), so draft gaps cannot be listed.')
+          exit 1
+        end
+
+        gap_states = report['violating_states'] || []
+        gaps = (report['drafts'] || []).filter_map do |row|
+          uncovered = Array(row['cells']).select { |c| gap_states.include?(c['state']) }
+          next if uncovered.empty?
+
+          { 'slug' => row['slug'], 'title' => row['title'], 'category' => row['category'],
+            'under_review' => false,
+            'surfaces' => uncovered.map { |c| { 'surface' => c['surface'], 'state' => c['state'] } } }
+        end
+        gaps = gaps.select { |gap| gap['category'] == opts[:category] } if opts[:category]
+
+        render_gaps(gaps, report, opts, drafts: true)
+      end
+
+      def render_gaps(gaps, report, opts, drafts: false)
         payload = {
           gaps: gaps,
           project: opts[:project],
@@ -199,9 +239,18 @@ module Fp
           category: opts[:category],
           summary: report['summary']
         }
+        payload[:status] = 'draft' if drafts
 
         output.success(payload) do
-          if gaps.empty?
+          if gaps.empty? && drafts
+            filter_desc = []
+            filter_desc << "category: #{opts[:category]}" if opts[:category]
+            filter_desc << "surface: #{opts[:surface]}" if opts[:surface]
+            msg = (report['drafts'] || []).empty? ? 'No draft requirements' : 'No draft gaps found'
+            msg += " (#{filter_desc.join(', ')})" unless filter_desc.empty?
+            puts "#{msg}."
+            next
+          elsif gaps.empty?
             filter_desc = []
             filter_desc << "category: #{opts[:category]}" if opts[:category]
             filter_desc << "surface: #{opts[:surface]}" if opts[:surface]
@@ -217,7 +266,7 @@ module Fp
             next
           end
 
-          desc = "Gaps for project '#{opts[:project]}'"
+          desc = "#{drafts ? 'Draft gaps' : 'Gaps'} for project '#{opts[:project]}'"
           desc += " (surface: #{opts[:surface]})" if opts[:surface]
           desc += " (category: #{opts[:category]})" if opts[:category]
           puts "#{desc}:"
@@ -234,6 +283,11 @@ module Fp
             puts
             puts "#{Parity::UNDER_REVIEW} #{Parity::UNDER_REVIEW_LEGEND} — check `fp history <slug>` before writing a test against wording that may be about to move."
           end
+
+          if drafts
+            puts
+            puts 'Drafts are reported, never gated. See every draft × surface with: fp coverage'
+          end
         end
       end