featureparity 0.0.26 → 0.0.28

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2403a7e55f95df5cf1821375442902c0a06784c26186f1e2fc1ae2e474ee937b
-  data.tar.gz: 4cbb3354c710f6d6e19114b2e2c28e533251c10bfa4a93c0a917ff73e5ebce93
+  metadata.gz: dd6b0a540d21e123a2ceb43cb9f23005c218319866ff7e079b951d6288199bb1
+  data.tar.gz: 6e0d61e3a3d9e6f590c6e978b134736877b5abc8da2a9a80332ff6cd203dbf58
 SHA512:
-  metadata.gz: 8a065b839f21e0bdf4194f65b93c233abf3e09ef11a50f96d0259d68609fc1c6e89e3d07e760a5a8d3b3bb12b849b7fdb7ea1c3a5fa65fc59b4befa053595366
-  data.tar.gz: 50e977bdf9a66c6f24a8a264d9334a506d5f15379f8e9aeaa8635d6cf84b5f9eee526e990c6e9b1a041631f1e15b7115e3ed3484311130f1fd23ca0ad7d35cde
+  metadata.gz: fe1d8110555996bc72c885d502139e6f18dbef1d2ee8b8623eaf48c74dce6c40b33f46ffe4b42f09c9f92570380abab9b4dff77df3520d300ec6f43f35214890
+  data.tar.gz: 1f95d64e43e62a63411bd8cc665248777c3acdc58795e16552d4b5f671d3a1fb89a774bbf066e5f65f55bba7b716cc5f2fa78d51ea2b1a5afdc1fcd547acfa2d

data/lib/fp/cli.rb

@@ -7,6 +7,7 @@ module Fp
   class CLI
     COMMANDS = {
       'init' => Commands::Init,
+      'tutorial' => Commands::Tutorial,
       'projects' => Commands::Projects,
       'surfaces' => Commands::Surfaces,
       'showroom' => Commands::Showroom,
@@ -15,12 +16,14 @@ module Fp
       'propose' => Commands::Propose,
       'propose-change' => Commands::ProposeChange,
       'comment' => Commands::Comment,
+      'comments' => Commands::Comments,
       'history' => Commands::History,
       'analyze' => Commands::Analyze,
       'changes' => Commands::Changes,
       'report' => Commands::Report,
       'ci-report' => Commands::CiReport,
       'changed-tests' => Commands::ChangedTests,
+      'spot-check' => Commands::SpotCheck,
       'check' => Commands::Check,
       'matrix' => Commands::Matrix,
       'export' => Commands::Export,

data/lib/fp/client.rb

@@ -208,6 +208,12 @@ module Fp
       post("/api/requirements/#{requirement_id}/analyze", body)
     end
 
+    # POST /requirements/:id/test_review — Jev's read of whether these tests check what
+    # the requirement promises (`fp spot-check --jev`). Paid plans only (402 otherwise).
+    def review_spot_check_tests(requirement_id, tests)
+      post("/api/requirements/#{requirement_id}/test_review", { tests: tests })
+    end
+
     # GET /requirements/:id/changes
     #
     # A requirement's change history: what it was, what changed, who changed it, and
@@ -241,6 +247,22 @@ module Fp
       post("/api/requirements/#{requirement_id}/changes/#{change_id}/comment", params)
     end
 
+    # GET /requirements/:id/comments
+    #
+    # The team's comments on a requirement, oldest first, plus who can be tagged:
+    # `mentionable` (people) and `mentionable_agents` (Fizzy #1494).
+    def list_requirement_comments(requirement_id)
+      get("/api/requirements/#{requirement_id}/comments")
+    end
+
+    # POST /requirements/:id/comments
+    #
+    # Comment on a requirement. `mentions` are emails, `agent_mentions` agent key ids;
+    # tagged people are emailed and tagged agents fire the project's webhooks.
+    def comment_on_requirement(requirement_id, params)
+      post("/api/requirements/#{requirement_id}/comments", params)
+    end
+
     # DELETE /requirements/:id/changes/:change_id
     #
     # Withdraw an open proposal. Only the proposal's author can withdraw it; the
@@ -513,7 +535,7 @@ module Fp
       http.read_timeout = 30
 
       response = http.request(request)
-      parse_response(response)
+      parse_response(response, uri)
     rescue Net::OpenTimeout, Net::ReadTimeout => e
       { ok: false, error: "Request timed out: #{e.message}", status: 0 }
     rescue SocketError, Errno::ECONNREFUSED => e
@@ -522,13 +544,20 @@ module Fp
       { ok: false, error: "Request failed: #{e.message}", status: 0 }
     end
 
-    def parse_response(response)
+    def parse_response(response, uri = nil)
       body = response.body
       status = response.code.to_i
 
       # Try to parse as JSON
       data = JSON.parse(body) rescue nil
 
+      # A success that isn't JSON is almost always the web app answering in the API's
+      # place — FP_API_URL set to the site rather than its api host — and every command
+      # used to crash on it with "undefined method '[]' for nil" (Fizzy #1446).
+      if status >= 200 && status < 300 && data.nil? && !body.to_s.strip.empty?
+        return { ok: false, status: status, error: not_the_api_message(uri) }
+      end
+
       if status >= 200 && status < 300
         { ok: true, data: data, status: status }
       else
@@ -544,5 +573,27 @@ module Fp
         result
       end
     end
+
+    def not_the_api_message(uri)
+      origin = uri ? "#{uri.scheme}://#{uri.host}" : @base_url
+      message = +"#{origin} answered with a web page, not the FeatureParity API. " \
+                 'Point fp at the API host instead (check it with `fp whoami`).'
+      suggestion = api_host_for(uri&.host)
+      message << " Did you mean https://#{suggestion}? (export FP_API_URL=https://#{suggestion})" if suggestion
+      message
+    end
+
+    # The API host that sits beside a web-app host: featureparity.dev → api.featureparity.dev,
+    # an ephemeral <env>.dev.featureparity.dev → api-<env>.dev.featureparity.dev.
+    def api_host_for(host)
+      return nil if host.nil? || host.start_with?('api.', 'api-')
+      return nil unless host.end_with?('featureparity.dev')
+
+      labels = host.split('.')
+      return "api.#{host}" if labels.length <= 2
+      return "api.#{host}" if labels.first == 'dev' || labels.first == 'staging'
+
+      "api-#{host}"
+    end
   end
 end

data/lib/fp/commands/analyze.rb

@@ -153,6 +153,7 @@ module Fp
           'duplicate_of' => issues.find { |i| i['type'] == 'duplicate' }&.dig('duplicate_of'),
           'conflicts' => (analysis && analysis['conflicts']) || [],
           'suggestions' => (analysis && analysis['suggestions']) || [],
+          'warrants_requirement' => analysis && analysis['warrants_requirement'],
           'error' => error
         }
       end
@@ -199,6 +200,8 @@ module Fp
         end
         puts "    fails: #{entry['failed_checks'].join(', ')}" unless entry['failed_checks'].empty?
         puts "    issues: #{entry['issues'].map { |i| i['type'] }.join(', ')}" unless entry['issues'].empty?
+        warrants = warrants_line(entry['warrants_requirement'])
+        puts "    #{warrants}" if warrants && entry['warrants_requirement']['judgment'] == false
         puts "    error: #{entry['error']}" if entry['error']
       end
 
@@ -206,6 +209,8 @@ module Fp
         puts "#{entry['slug']} — #{entry['title']}"
         puts "  verdict: #{entry['verdict'] || '(none)'}   suggested: #{ACTIONS[entry['action']]}"
         puts "  superseded by: #{entry['duplicate_of']}" if entry['duplicate_of']
+        warrants = warrants_line(entry['warrants_requirement'])
+        puts "  #{warrants}" if warrants
         puts "  fails: #{entry['failed_checks'].join(', ')}" unless entry['failed_checks'].empty?
         entry['issues'].each { |i| puts "  issue: #{i['type']}" }
         entry['conflicts'].each do |c|
@@ -215,6 +220,18 @@ module Fp
         puts "  error: #{entry['error']}" if entry['error']
       end
 
+      # The analyzer's yes/no on whether the concept deserves to be a requirement at all.
+      # A "no" carries its reason so a human can decide to withdraw it — the CLI only
+      # reports it; nothing is withdrawn or proposed on the strength of the judgment.
+      def warrants_line(warrants)
+        return nil unless warrants.is_a?(Hash) && [true, false].include?(warrants['judgment'])
+
+        line = "warrants a requirement: #{warrants['judgment'] ? 'yes' : 'no'}"
+        line += " (confidence #{(warrants['confidence'].to_f * 100).round}%)" unless warrants['confidence'].nil?
+        line += " — #{warrants['reason']}" if !warrants['judgment'] && !warrants['reason'].to_s.empty?
+        line
+      end
+
       def progress(message)
         warn message unless output.json?
       end

data/lib/fp/commands/base.rb

@@ -202,6 +202,8 @@ module Fp
 
         unless project
           output.error("Project '#{project_slug_or_id}' not found")
+          hint = config&.environment_mismatch_hint
+          output.error(hint) if hint
           exit 1
         end
 

data/lib/fp/commands/comments.rb

@@ -0,0 +1,146 @@
+# frozen_string_literal: true
+
+module Fp
+  module Commands
+    # `fp comments <slug>` — the team's conversation on a requirement (Fizzy #1494).
+    #
+    # Without --body it prints the comments, oldest first. With --body it posts one, and
+    # --tag names who to tag: a teammate by email or name, or one of the team's agents by
+    # name or key name. Tagged people are emailed; each tagged agent fires the project's
+    # `requirement.agent_mentioned` webhooks, so whatever runs that agent can pick it up.
+    #
+    # Not to be confused with `fp comment`, which threads a comment onto a requirement's
+    # open change *proposal*.
+    class Comments < Base
+      KNOWN_FLAGS = { project: :string, body: :string, tag: :string }.freeze
+
+      help_summary "Read or post the team's comments on a requirement, tagging people or agents"
+      help_usage 'fp comments <slug> [--body "..." [--tag <who>,<who>]] --project <slug>'
+      help_flag :project, 'Project slug (falls back to .featureparity.yml)'
+      help_flag :body, 'Post this comment (omit to list the comments)'
+      help_flag :tag, 'Comma-separated people (email or name) or agents (name or key name) to tag'
+      help_example 'fp comments print_qr --project stowzilla'
+      help_example 'fp comments print_qr --body "The redesign dropped this screen — retire it?" --tag andy@example.com'
+
+      def run(args)
+        opts, positional = parse_flags(args, KNOWN_FLAGS)
+        require_project!(opts)
+
+        slug = positional.first
+        unless slug
+          output.error('Requirement slug is required. Usage: fp comments <slug> [--body "..."] [--project <project>]')
+          exit 1
+        end
+
+        project_id = resolve_project_id(opts[:project])
+        requirement = find_requirement!(project_id, slug)
+        listing = fetch!(client.list_requirement_comments(requirement['id']))
+
+        if opts[:body].nil?
+          print_comments(listing, slug)
+        else
+          post_comment(requirement, listing, opts, slug)
+        end
+      end
+
+      private
+
+      def post_comment(requirement, listing, opts, slug)
+        body = opts[:body].to_s
+        if body.strip.empty?
+          output.error('A comment needs some text. Pass --body "...".')
+          exit 1
+        end
+
+        people, agents = resolve_tags(opts[:tag], listing)
+        data = fetch!(client.comment_on_requirement(requirement['id'],
+                                                    body: body,
+                                                    mentions: people.map { |p| p['email'] },
+                                                    agent_mentions: agents.map { |a| a['id'] }))
+        comment = data['comment'] || {}
+
+        output.success(data) do
+          puts "Commented on '#{slug}'."
+          puts
+          print_comment(comment)
+          tagged_people = Array(comment['mentions']).map { |m| m['name'] }
+          tagged_agents = Array(comment['agent_mentions']).map { |m| m['name'] }
+          puts "#{tagged_people.join(', ')} will get an email." unless tagged_people.empty?
+          puts "#{tagged_agents.join(', ')} will be notified through the project's webhooks." unless tagged_agents.empty?
+        end
+      end
+
+      # Each --tag matches exactly one person (email or name) or agent (name or key
+      # name), case-insensitively. Unknown or ambiguous tags stop the command rather
+      # than post a comment that silently tags nobody.
+      def resolve_tags(raw, listing)
+        people = []
+        agents = []
+        raw.to_s.split(',').map(&:strip).reject(&:empty?).each do |tag|
+          wanted = tag.delete_prefix('@').downcase
+          person_hits = Array(listing['mentionable']).select do |p|
+            [p['email'], p['name']].compact.map(&:downcase).include?(wanted)
+          end
+          agent_hits = Array(listing['mentionable_agents']).select do |a|
+            [a['name'], a['key_name']].compact.map(&:downcase).include?(wanted)
+          end
+          hits = person_hits + agent_hits
+          if hits.empty?
+            output.error("Nobody on this project's team matches '#{tag}'. Run `fp comments <slug>` to see who can be tagged.")
+            exit 1
+          elsif hits.size > 1
+            output.error("'#{tag}' matches more than one person or agent; use an email or key name instead.")
+            exit 1
+          end
+          person_hits.empty? ? agents << agent_hits.first : people << person_hits.first
+        end
+        [people, agents]
+      end
+
+      def print_comments(listing, slug)
+        comments = Array(listing['comments'])
+        output.success(listing) do
+          puts "Comments on '#{slug}'"
+          puts
+          if comments.empty?
+            puts '  (no comments yet)'
+          else
+            comments.each { |comment| print_comment(comment) }
+          end
+          print_taggable(listing)
+        end
+      end
+
+      def print_comment(comment)
+        kind = comment['actor_kind'] == 'agent' ? ' (agent)' : ''
+        puts "* #{comment['actor_name'] || comment['actor']}#{kind} at #{comment['recorded_at']}"
+        comment['body'].to_s.each_line { |line| puts "  > #{line.chomp}" }
+        tags = Array(comment['mentions']) + Array(comment['agent_mentions'])
+        puts "  tagged: #{tags.map { |t| t['name'] }.join(', ')}" unless tags.empty?
+        puts
+      end
+
+      def print_taggable(listing)
+        people = Array(listing['mentionable']).map { |p| "#{p['name']} <#{p['email']}>" }
+        agents = Array(listing['mentionable_agents']).map { |a| "#{a['name']} (#{a['key_name']}, #{a['owner_name']}'s agent)" }
+        return if people.empty? && agents.empty?
+
+        puts 'Can be tagged with --tag:'
+        people.each { |p| puts "  #{p}" }
+        agents.each { |a| puts "  #{a}" }
+      end
+
+      def find_requirement!(project_id, slug)
+        fetch!(client.find_requirement_by_slug(project_id, slug))['requirement']
+      end
+
+      def fetch!(result)
+        unless result[:ok]
+          output.error(result[:error], status: result[:status])
+          exit 1
+        end
+        result[:data]
+      end
+    end
+  end
+end

data/lib/fp/commands/help.rb

@@ -39,6 +39,7 @@ module Fp
 
           COMMANDS
             init --project <slug>             Onboard this repo: config, CI gate, agent docs
+            tutorial                          Write Hexhaven, a sample repo to practise on
             projects                          List projects you have access to
             projects show <slug>              View a project and its surfaces
             projects create <slug> --name ... Create a project (owned by your key's owner)
@@ -62,6 +63,8 @@ module Fp
             propose-change <slug> --no-parent Propose un-nesting a child to top level
             propose-change <slug> --withdraw  Withdraw your own open proposal (to amend it)
             comment <slug> --body "..."       Comment on a requirement's open change proposal
+            comments <slug>                   Read the team's comments on a requirement
+            comments <slug> --body "..." [--tag who,...]  Comment on a requirement, tagging people or agents
             history <slug> --project <slug>   Show a requirement's change history + diffs
             analyze [<slug>] --project <slug> Triage requirement quality (read-only; never proposes)
             changes [--source-url URL] [--github-pr]  Show or publish work-item-linked activity
@@ -76,6 +79,7 @@ module Fp
             ci-report --junit <file> --pr URL Ingest a PR's CI results as pr_passing — CI only
             changed-tests                     List unresolved bound-test revision findings
             changed-tests assess <id> ...     Explain whether an exact revision still proves its requirement
+            spot-check [<slug>...]            Check requirements' tests prove them (random, --count, --all, --test)
             check                             Enforce parity; exits non-zero on violations
             matrix --project <slug>           Show the parity matrix
             export --project <slug>           Export all requirements as a Markdown document
@@ -159,6 +163,30 @@ module Fp
             A stale or later candidate needs a new assessment. A PR candidate becomes accepted only
             when a default-branch CI report later observes the same fingerprint.
 
+          SPOT CHECKS
+            A green receipt says a marked test ran and passed, not that it checks what the
+            requirement promises. `fp spot-check` picks an active requirement with evidence at
+            random, prints its acceptance beside the source of every locally marked test, and
+            gives the agent running it a brief: match each clause to an assertion, then break
+            the product code and confirm a test fails. Run it on a schedule or by hand.
+
+              fp spot-check                     # a random pick; prints the seed to repeat it
+              fp spot-check --count 5 --surface cli --json
+              fp spot-check print_container_qr print_label   # chosen requirements
+              fp spot-check --all               # every active requirement with evidence
+              fp spot-check --test test/qr_test.rb:42        # the test there, and its requirement
+              fp spot-check --count 3 --prompt | claude -p   # hand it straight to an agent
+              fp spot-check --jev               # add Jev's first read (paid plans)
+
+            `--prompt` prints the spot check as instructions for an agent, with what to report
+            back. `--jev` asks Jev, before the agent starts, whether each requirement's tests
+            appear to cover its acceptance, and which gap is likeliest. It's a hint for aiming
+            the probe, not a verdict. Jev is for paid plans: without one the spot check runs
+            without it.
+
+            It records nothing and never edits a test or a requirement. A test that stays
+            green when the promise is broken goes to a human.
+
           AUTHENTICATION
             Set FP_API_KEY environment variable, or use a profile:
 
@@ -289,24 +317,32 @@ module Fp
             #
             # Write the requirement as a product decision someone can approve, not a design
             # task. It should sound like a capable teammate, not AI boilerplate.
-            #   title: one product promise in present tense, not the implementation project
-            #   why: one or two natural sentences naming the user need/problem and outcome
-            #   acceptance: trigger or situation + observable result + material boundaries
-            # Use examples and tests to ground and double-check the general rule, not to replace
-            # it or ongoing conversation. Leave out components, data models, algorithms, endpoints,
-            # and UI controls unless they are themselves part of the user-visible contract.
-            # Include a price, quota, timeout, count, date,
-            # role, or fallback only when the source made it a real product decision; if an
-            # important policy is missing, ask instead of inventing a plausible value.
+            #   title: one product promise in present tense, with a concrete subject and active verb
+            #   why: one natural sentence naming the user need/problem and protected outcome
+            #   acceptance: one independently verifiable rule of observable behaviour;
+            #               append one concise concrete case as "Example: ..."
+            # Given/When/Then may clarify a rule, but is not mandatory. Split another result that
+            # could fail independently rather than comma-chaining it into the same requirement.
+            # Use the domain's real terms in examples and ask rather than invent consequential
+            # policy. Examples and tests ground and double-check the rule; they do not replace it.
+            # State each field directly. Avoid “This feature…”, “The goal is…”, “Users should be
+            # able to…”, “The system should…”, and task titles beginning “Enable” or “Implement”.
+            # Leave out components, data models, algorithms, endpoints, and UI controls unless
+            # they are themselves part of the user-visible contract.
+            # Include a price, quota, timeout, count, date, role, or fallback only when the source
+            # made it a real product decision; if important policy is missing, ask instead of
+            # inventing a plausible value.
             #
             #   good title:      "Dispatchers see current shipment status"
             #   good why:        "Dispatchers need to spot delayed shipments before they miss a delivery window."
             #   good acceptance: "When status changes, the dashboard shows it; when unavailable, it says so instead of showing stale data as current."
             #   bad: "Implement Redis polling every 30 seconds to ensure a seamless experience."
             #        (invented policy, implementation detail, and filler; no product outcome)
-            # Before saving, read it as a manager deciding scope: is the value clear, is the
-            # result observable, are decisions separated from guesses, and does every sentence
-            # earn its place?
+            # Before saving, answer against the actual fields: who is this promise for, how would
+            # the concrete example prove it done, and why does the outcome matter? If an answer is
+            # vague, revise or ask. Then read it as a manager deciding scope: is the value clear,
+            # is the result observable, are decisions separated from guesses, and does every
+            # sentence earn its place? Do not save until the draft passes this review.
             fp propose --project stowzilla \\
               --slug print_container_qr \\
               --name "Print QR code on container label" \\

data/lib/fp/commands/history.rb

@@ -31,7 +31,9 @@ module Fp
         'removal_proposed' => 'deletion proposed',
         'change_approved' => 'change approved',
         'change_rejected' => 'change rejected',
-        'decision_recorded' => 'decision recorded'
+        'decision_recorded' => 'decision recorded',
+        'change_commented' => 'commented on the proposal',
+        'commented' => 'commented'
       }.freeze
 
       # A member's own stance on a requirement that already has a status (Fizzy #1478),
@@ -110,6 +112,7 @@ module Fp
         puts "* #{label} — #{actor} (#{kind}) at #{format_time(change['recorded_at'])}"
         puts "  #{change['reason']}" if present?(change['reason'])
         puts "  note: #{change['note']}" if change['type'] == 'decision_recorded' && present?(change['note'])
+        print_comment(change) if %w[commented change_commented].include?(change['type'])
         print_source(change['source'])
         print_diff(change['changes'])
         print_evidence_diff(change['evidence_diff'])
@@ -117,6 +120,14 @@ module Fp
         puts
       end
 
+      # The team's comments (Fizzy #1494) and comments on a proposal, so an agent reading
+      # the history sees the discussion, not just that one happened.
+      def print_comment(change)
+        change['body'].to_s.each_line { |line| puts "  > #{line.chomp}" } if present?(change['body'])
+        mentions = Array(change['mentions'])
+        puts "  tagged: #{mentions.join(', ')}" unless mentions.empty?
+      end
+
       def print_source(source)
         return if source.nil? || source.empty?
 

data/lib/fp/commands/init.rb

@@ -88,6 +88,15 @@ 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
+
       private
 
       def write_project_config(root, project_slug, level, opts, written, skipped)
@@ -470,18 +479,22 @@ module Fp
           task.** It should read like a capable teammate wrote it: direct, specific, and free
           of boilerplate such as “ensure a seamless experience.”
 
-          - **Title:** one clear product promise in present tense. Name the user-visible
-            capability, not the work (`“Dispatchers see current shipment status”`, not
-            `“Implement status polling”`).
-          - **Why:** one or two natural sentences naming who needs this, the problem or risk,
-            and the outcome worth protecting. Do not repeat the title, sell the feature, or
-            explain the mechanism.
-          - **Acceptance:** the observable behaviour that would let a reviewer decide whether
-            the promise is true. State the trigger or situation, the result, and material
-            boundaries such as permissions, failure states, and affected surfaces. Use examples
-            and marked tests to ground and double-check the rule. Do not mistake a few examples for the rule
-            or let tests stand for every case; neither replaces the general rule and continued
-            conversation.
+          - **Title:** one clear product promise in present tense, with a concrete subject and
+            active verb. Name the user-visible capability, not the work (`“Dispatchers see
+            current shipment status”`, not `“Implement status polling”`).
+          - **Why:** one natural sentence naming who needs this, the problem or risk, and the
+            outcome worth protecting. Do not repeat the title, narrate the request or bug
+            history, sell the feature, or explain the mechanism.
+          - **Acceptance:** one independently verifiable rule of observable behaviour that lets a
+            reviewer decide whether the promise is true. State the trigger or situation, the result, and material
+            boundaries that qualify that same promise. Given/When/Then may clarify those parts,
+            but it is not a mandatory template. Split a second result that could fail
+            independently into its own requirement instead of comma-chaining it here.
+          - **Example:** supply one concise concrete case that would pass the general rule, and
+            put it after the rule in Acceptance as `Example: ...`. Use the domain's real terms
+            and representative data, but ask rather than invent consequential policy. Do not mistake a few examples for the rule
+            or let marked tests stand for every case; neither replaces the general rule and
+            continued conversation.
           - **Numbers and policy:** include a price, limit, timeout, date, role, or fallback only
             when the source made it a real product decision. Never invent a plausible value to
             fill a gap. If the decision matters and the source is silent, ask.
@@ -494,6 +507,10 @@ module Fp
           unquestionable scope. Preserve important uncertainty as a question rather than
           laundering a guess into acceptance criteria.
 
+          State the promise itself rather than commentary about it. Avoid openings such as “This
+          feature…”, “This requirement…”, “The goal is…”, “Users should be able to…”, and “The
+          system should…”. Use the real actor or product as the subject and an active verb.
+
           - ✅ **Title:** `Dispatchers see current shipment status`
             **Why:** `Dispatchers need to spot delayed shipments before they miss a delivery window.`
             **Acceptance:** `When a shipment's status changes, the dashboard shows the new status; if status is unavailable, it says so instead of presenting stale data as current.`
@@ -502,9 +519,12 @@ module Fp
             **Acceptance:** `Use a background worker and refresh every 30 seconds.`
             This invents policy, prescribes a design, and never states the product outcome.
 
-          Before proposing, read the draft once as a manager deciding scope: is the value clear,
-          can the result be observed, are product decisions distinguished from guesses, and can
-          every sentence earn its place? If not, revise or ask before writing the record.
+          Before proposing, answer three questions against the actual fields: Who is this promise
+          for? How would the concrete example prove it done? Why does the outcome matter? If any
+          answer is missing or vague, revise the draft or ask the user. Then read it as a manager deciding scope:
+          is the value clear, can the result be observed, are product decisions
+          distinguished from guesses, and does every sentence earn its place? If the draft fails
+          this review, revise it or ask before writing the record.
 
           ### 2. If the requirement is wrong, propose a change — don't silently edit it
 

data/lib/fp/commands/projects.rb

@@ -87,7 +87,11 @@ module Fp
         output.success(result[:data]) do
           if projects.empty?
             puts 'No projects found.'
-            puts 'Create one with: fp projects create <slug> --name "<Name>"'
+            if (hint = config&.environment_mismatch_hint)
+              puts hint
+            else
+              puts 'Create one with: fp projects create <slug> --name "<Name>"'
+            end
           else
             headers = %w[SLUG NAME SURFACES]
             rows = projects.map do |w|

data/lib/fp/commands/propose.rb

@@ -108,8 +108,10 @@ module Fp
         end
 
         requirement = result[:data]['requirement']
+        feedback = draft_feedback(requirement)
+        data = result[:data].merge('analysis' => feedback[:analysis], 'analysis_error' => feedback[:error]).compact
 
-        output.success(result[:data]) do
+        output.success(data) do
           puts "Created requirement '#{requirement['slug']}' as DRAFT."
           puts
           puts "  Title:    #{requirement['title']}"
@@ -125,11 +127,42 @@ module Fp
           puts '⚠️  This requirement is a DRAFT.'
           puts '   A human must activate it in the web app before it appears in the parity matrix.'
           puts '   Agents cannot activate requirements.'
+          print_feedback(feedback, requirement['slug'])
         end
       end
 
       private
 
+      # Quality feedback on the draft just created, as part of the same command, so an
+      # agent learns at once that its draft is weak or shouldn't exist and can fix or
+      # withdraw it before a human looks (requirement_analysis_runs_on_draft). It never
+      # undoes the draft: when analysis is unavailable the draft stands and we say so.
+      def draft_feedback(requirement)
+        result = client.analyze_requirement(requirement['id'])
+        return { analysis: result[:data]['analysis'] } if result[:ok] && result[:data].is_a?(Hash) && result[:data]['analysis']
+
+        { error: result[:error] || 'no analysis came back' }
+      end
+
+      def print_feedback(feedback, slug)
+        puts
+        if feedback[:error]
+          puts "Quality feedback could not be produced: #{feedback[:error]}"
+          puts "The draft was still created. Try again later with `fp analyze #{slug}`."
+          return
+        end
+
+        analysis = feedback[:analysis]
+        puts "Quality feedback: #{analysis['verdict'] || 'no verdict'}"
+        Array(analysis['issues']).each do |issue|
+          puts "  - #{issue['type'].to_s.tr('_', ' ')}"
+        end
+        Array(analysis['suggestions']).first(3).each { |suggestion| puts "  → #{suggestion}" }
+        return unless %w[questionable needs_work].include?(analysis['verdict'])
+
+        puts "Revise it with `fp propose-change #{slug} ...`, or withdraw it if it shouldn't be a requirement."
+      end
+
       # Parse a comma-separated --required-types list into a normalized array. Returns []
       # when the flag is absent (meaning "any test counts / inherit project default").
       #

data/lib/fp/commands/propose_change.rb

@@ -23,16 +23,16 @@ module Fp
       help_flag :parent, "Set the parent requirement's slug"
       help_flag :no_parent, 'Propose un-nesting the requirement back to the top level (clears --parent)'
       help_flag :slug, 'Proposed new slug (evidence follows; markers still need updating)'
-      help_flag :reason, 'What prompted this change (use this, not --source-*, to record the prompt)'
+      help_flag :reason, 'What prompted this change, in words (recorded on the change)'
       help_flag :removal, 'Propose deleting the requirement instead of changing it'
       help_flag :withdraw, 'Take back the open proposal you authored, restoring the requirement as it was'
-      help_flag :source_type, "Correct the requirement's recorded origin type (not the change's prompt)"
-      help_flag :source_url, "Correct the requirement's recorded origin URL"
-      help_flag :source_context, "Correct the requirement's recorded origin context"
+      help_flag :source_type, "Where this proposal came from (recorded on the change; the requirement's origin is kept)"
+      help_flag :source_url, 'URL of the card/issue/thread that prompted this proposal'
+      help_flag :source_context, 'Free-form note about what prompted this proposal'
       help_example 'fp propose-change print_qr --project stowzilla --acceptance "QR scans after 24h at -20C" --reason "Cold-chain rollout"'
       help_example 'fp propose-change print_qr --removal --reason "Superseded by print_container_label"'
-      help_note "Applies the change and drops the requirement to draft for a human to review. Use --reason\n" \
-                "to say what prompted it; --source-* overwrite the requirement's own origin fields."
+      help_note "Applies the change and drops the requirement to draft for a human to review. --reason and\n" \
+                "--source-* record what prompted the proposal in its history; the requirement's own origin is unchanged."
 
       KNOWN_FLAGS = {
         project: :string, name: :string, why: :string, acceptance: :string,