featureparity 0.0.21 → 0.0.22

data/lib/fp/commands/comment.rb

@@ -19,6 +19,16 @@ module Fp
 
       VALID_SOURCE_TYPES = %w[fizzy discord github_issue jira notion manual ai_chat].freeze
 
+      help_summary "Comment on a requirement's open change proposal"
+      help_usage 'fp comment <slug> --body "..." --project <slug>'
+      help_flag :project, 'Project slug (falls back to .featureparity.yml)'
+      help_flag :body, 'The comment text', required: true
+      help_flag :change, 'Target a specific change id (defaults to the open proposal)'
+      help_flag :source_type, "Origin type: #{VALID_SOURCE_TYPES.join(', ')}"
+      help_flag :source_url, 'Origin URL'
+      help_flag :source_context, 'Free-form origin note'
+      help_example 'fp comment print_qr --body "This conflicts with the freezer label requirement" --project stowzilla'
+
       def run(args)
         opts, positional = parse_flags(args, KNOWN_FLAGS)
         require_project!(opts)

data/lib/fp/commands/config_cmd.rb

@@ -5,6 +5,15 @@ module Fp
     # fp config get|set|unset|list
     # Manage global CLI settings (stored in ~/.config/fp/config.yml)
     class ConfigCmd < Base
+      help_summary 'Manage global CLI settings (stored in ~/.config/fp/config.yml)'
+      help_usage 'fp config set <key> <value>',
+                 'fp config get <key>',
+                 'fp config unset <key>',
+                 'fp config list'
+      help_example 'fp config set api_url https://api.featureparity.dev'
+      help_example 'fp config list'
+      help_note "Allowed settings: api_url. 'fp config whoami' is an alias for 'fp whoami'."
+
       ALLOWED_SETTINGS = %w[api_url].freeze
 
       def run(args)

data/lib/fp/commands/conversation.rb

@@ -17,6 +17,11 @@ module Fp
     #   4. Agent runs `fp conversation <id>` to read the full context
     #   5. Agent implements based on Pari's suggestions
     class Conversation < Base
+      help_summary 'Read a Pari conversation so an agent can review AI suggestions'
+      help_usage 'fp conversation <conversation-id>'
+      help_example 'fp conversation 03h0abc123xyz'
+      help_note 'No --project needed; works for project and account-level conversations.'
+
       def run(args)
         _opts, positional = parse_flags(args)
         conversation_id = positional.first

data/lib/fp/commands/export.rb

@@ -11,6 +11,16 @@ module Fp
     # attached to a release as a point-in-time record of what the product is
     # supposed to do.
     class Export < Base
+      help_summary 'Export all requirements as a single Markdown document'
+      help_usage 'fp export --project <slug> [--status S] [--category C] [--surface X] [--output FILE]'
+      help_flag :project, 'Project slug (falls back to .featureparity.yml)'
+      help_flag :status, 'Only requirements with this status'
+      help_flag :category, 'Only requirements in this category'
+      help_flag :surface, 'Only requirements that name this surface'
+      help_flag :output, 'Write to this file instead of stdout'
+      help_example 'fp export --project stowzilla > requirements.md'
+      help_example 'fp export --project stowzilla --status active --surface customer_android --output reqs.md'
+
       KNOWN_FLAGS = {
         project: :string,
         status: :string,

data/lib/fp/commands/help.rb

@@ -2,37 +2,66 @@
 
 module Fp
   module Commands
-    # fp help
+    # fp help [<command>]
+    #
+    # With no argument, prints the top-level usage. With a command name, prints that
+    # command's own help — the same page `fp <command> --help` shows (Fizzy #1489).
     class Help < Base
-      def run(_args)
+      def run(args)
+        topic = args.first
+        if topic && Fp::CLI::COMMANDS.key?(topic)
+          puts Fp::CLI::COMMANDS[topic].help_text(topic)
+          return
+        end
+
+        if topic && !topic.start_with?('-')
+          output.error("Unknown command: #{topic}") if output
+          warn "Unknown command: #{topic}" unless output
+          puts "\nRun 'fp help' for the list of commands."
+          return
+        end
+
+        print_overview
+      end
+
+      private
+
+      def print_overview
         puts <<~HELP
           fp - FeatureParity CLI for agents
 
           USAGE
             fp <command> [flags]
+            fp <command> --help               Show a command's own usage and flags
+            fp <command> --help --json        ...as a machine-readable flag schema
+            fp help <command>                 Same, spelled the other way
+            fp --version                      Show the installed version (alias: -v)
 
           COMMANDS
             init --project <slug>             Onboard this repo: config, CI gate, agent docs
             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)
-            projects edit <slug> --name ...   Update a project's name or description
+            projects edit <slug> --name ...   Update a project's name, description, or showroom welcome
             projects delete <slug> [--yes]    Delete a project (asks you to type its slug)
             surfaces --project <slug>         List surfaces for a project
             surfaces show <key> --project ... View a single surface's details
             surfaces add <key> --project ...  Create a surface
-            surfaces edit <key> --project ... Change a surface (name, kind, repo, key...)
+            surfaces edit <key> --project ... Change a surface (name, kind, repo, key, showroom card...)
             surfaces delete <key> --project . Delete a surface (asks first; --yes to skip)
+            showroom --project <slug>         Preview the client showroom as a client sees it
             list --project <slug>             List active requirements
             show <slug> --project <slug>      Show requirement details
             propose --project <slug> ...      Propose a new requirement (as draft)
             propose-change <slug> ...         Propose a change to an existing requirement
             propose-change <slug> --removal   Propose deleting a requirement
+            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
             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
-            attach <slug> <file>              Upload a file attachment to a requirement
+            attach <slug> <file> [<file>...]  Upload one or more file attachments to a requirement
             attachments <slug>                List attachments for a requirement
             attachments <slug> <id>           Get download URL for an attachment
             attach rm <slug> <id>             Delete an attachment
@@ -51,7 +80,7 @@ module Fp
             whoami                            Show the resolved config (profile, env, API URL, key)
             repos set|get|list|unset          Map surfaces to local repo paths
             setup                             Interactive first-time setup
-            version                           Show version
+            version                           Show version (also: fp --version, fp -v)
             help                              Show this help
 
           GLOBAL FLAGS
@@ -66,6 +95,24 @@ module Fp
             so a checkout declares its own project once instead of every CI job and agent
             repeating it. `fp init` writes that file.
 
+          CLIENT SHOWROOM
+            The showroom is the one page a client sees: a welcome note, then a card per
+            surface with a link, a button label, and sign-in instructions. The team's
+            agents keep that content, because the agent that deployed a surface and made
+            its demo accounts is the one that knows the URL and the credentials:
+
+              fp projects edit <slug> --showroom-welcome "Hi Sam, here's what we built." \\
+                                      # or --showroom-welcome-file welcome.txt
+              fp surfaces edit web --showroom-url https://dev.example.com \\
+                                   --showroom-label "Open the web app" \\
+                                   --showroom-instructions-file docs/showroom/web.txt
+              fp showroom          # what the client will see, and which surfaces are hidden
+
+            A surface is shown once it has a link or instructions; pass an empty value
+            to clear a field (`--showroom-url ""`) and a surface with neither drops out.
+            Leaving feedback and turning the share link on or off are for humans, in the
+            web app under Project Settings → Showroom.
+
           ENFORCEMENT
             `fp check` fails a build when the project violates its enforcement level. Make it
             a required status check on your default branch to block merges.
@@ -287,6 +334,15 @@ module Fp
               --removal \\
               --reason "Superseded by print_container_label"
 
+            # Un-nest a child back to the top level (clears its parent)
+            fp propose-change print_container_qr_ios --project stowzilla --no-parent \\
+              --reason "Promoted to a top-level promise"
+
+            # Amend a proposal you already opened: the single-open-proposal rule won't let
+            # you open a second, so withdraw yours (restoring the requirement) and propose
+            # again. Only the author can withdraw; someone else's proposal goes to review.
+            fp propose-change print_container_qr --project stowzilla --withdraw
+
             # See what changed, why, and who asked for it
             fp history print_container_qr --project stowzilla
             fp history print_container_qr --project stowzilla --pending
@@ -357,6 +413,18 @@ module Fp
               --work-item https://app.fizzy.do/123/cards/456
             # --base-dir sets where relative test file paths in the report resolve from
             # Skipped tests are reported as 'stub'; everything else as 'present'.
+            # --test-type sets the kind of test (unit, e2e, ...) for markers that pin
+            # none. Give a different suite (e.g. a Playwright e2e run) its own type, or
+            # evidence for the same requirement+surface collides on the 'unspecified'
+            # bucket and the last report silently overwrites the earlier ones.
+
+            # Playwright's JUnit reporter is understood natively: titles joined with
+            # › (or :: for pytest-style ids) bind by name, a classname relative to the
+            # runner's testDir is searched for under base-dir, and --attach-media uploads
+            # the videos/screenshots the run recorded ([[ATTACHMENT|…]]) as visual
+            # evidence, each nested under the test it proves.
+            fp report --junit junit.xml --project stowzilla \\
+              --surface web --repo stowzilla/app --base-dir frontend --attach-media
 
             # CI ONLY: ingest real pass/fail results. Run in your CI pipeline after
             # the suite (on green AND red builds). Unlike `fp report`, this writes

data/lib/fp/commands/history.rb

@@ -9,6 +9,14 @@ module Fp
     # proposal, if there is one, is called out at the end because that's the thing
     # someone still has to decide on.
     class History < Base
+      help_summary "A requirement's change history: what changed, who changed it, and why"
+      help_usage 'fp history <slug> --project <slug> [--pending] [--limit N]'
+      help_flag :project, 'Project slug (falls back to .featureparity.yml)'
+      help_flag :pending, 'Show only the open proposal, if any'
+      help_flag :limit, 'Cap the number of events shown'
+      help_example 'fp history print_container_qr --project stowzilla'
+      help_example 'fp history print_container_qr --project stowzilla --pending'
+
       KNOWN_FLAGS = { project: :string, pending: :boolean, limit: :string }.freeze
 
       # Human labels for event types. The wire values are stable identifiers; these are

data/lib/fp/commands/init.rb

@@ -23,6 +23,19 @@ module Fp
     # unless --force, and the AGENTS.md section is appended once and detected by a
     # 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_flag :project, 'Project slug to record in .featureparity.yml', required: true
+      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)'
+      help_flag :force, 'Refresh files fp previously wrote'
+      help_flag :no_workflow, 'Skip writing the CI workflow'
+      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.'
+
       KNOWN_FLAGS = {
         project: :string,
         surface: :string,
@@ -174,6 +187,9 @@ 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
           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'
           puts 'the level to `covered` or `strict` once the gaps are paid down.'
@@ -218,6 +234,13 @@ module Fp
               permissions:
                 contents: read
                 pull-requests: write
+              # Whether the FP_API_KEY secret exists on this repo. Every step that talks
+              # to FeatureParity is guarded on this, so the very first push — before
+              # anyone has added the secret — explains what to do instead of dying with a
+              # bare "No API key found" from fp. Fork pull requests also can't read the
+              # secret, and are skipped the same way.
+              env:
+                HAVE_FP_KEY: ${{ secrets.FP_API_KEY != '' }}
               steps:
                 - uses: actions/checkout@v4
 
@@ -228,8 +251,30 @@ module Fp
                 - name: Install fp
                   run: gem install featureparity
 
+                # Without the secret there is nothing the gate can do yet, so say so
+                # clearly (in the job summary and the log) and let the build pass. This is
+                # the expected state right after `fp init`: the repo is onboarded, the
+                # maintainer just hasn't added the key. A green, explanatory run beats a
+                # red one nobody can action.
+                - name: FeatureParity not configured yet
+                  if: env.HAVE_FP_KEY != 'true'
+                  run: |
+                    {
+                      echo '## FeatureParity gate skipped'
+                      echo ''
+                      echo 'The `FP_API_KEY` secret is not set on this repository, so the parity'
+                      echo 'gate cannot run yet. This is expected on the first push after `fp init`.'
+                      echo ''
+                      echo 'To enable the gate, add a repository secret named `FP_API_KEY`'
+                      echo '(Settings → Secrets and variables → Actions → New repository secret).'
+                      echo 'Mint a key at https://featureparity.dev (Account → Agents & API keys).'
+                      echo ''
+                      echo 'Fork pull requests cannot read the secret and will always show this.'
+                    } >> "$GITHUB_STEP_SUMMARY"
+                    echo 'FP_API_KEY is not set — skipping the parity gate. See the job summary.'
+
                 - name: Update PR requirement changes
-                  if: github.event_name == 'pull_request'
+                  if: github.event_name == 'pull_request' && env.HAVE_FP_KEY == 'true'
                   env:
                     FP_API_KEY: ${{ secrets.FP_API_KEY }}
                     GITHUB_TOKEN: ${{ github.token }}
@@ -247,6 +292,9 @@ module Fp
                 # Add `--warn-only` while adopting if you need the annotations without
                 # blocking merges yet.
                 #
+                # Guarded on HAVE_FP_KEY so a repo that hasn't added the secret yet gets
+                # the explanatory step above instead of a bare "No API key found" failure.
+                #
                 # NOTE: as written this gates on what has been *recorded*, which on a pull
                 # request is the default branch's state. To judge a branch on its own
                 # results, emit JUnit in this job and pass it — nothing is saved:
@@ -258,6 +306,7 @@ module Fp
                 # suite stays green while the requirement loses its only proof. Use one
                 # call per surface.
                 - name: Check parity
+                  if: env.HAVE_FP_KEY == 'true'
                   env:
                     FP_API_KEY: ${{ secrets.FP_API_KEY }}
                   run: fp check

data/lib/fp/commands/list.rb

@@ -5,6 +5,18 @@ module Fp
     # fp list --project <slug> [--surface X] [--category Y] [--gaps] [--status draft]
     # List requirements, optionally filtered
     class List < Base
+      help_summary 'List requirements, optionally filtered'
+      help_usage 'fp list --project <slug> [--surface X] [--category Y] [--tag Z] [--status S] [--gaps]'
+      help_flag :project, 'Project slug (falls back to .featureparity.yml)'
+      help_flag :surface, 'Only requirements that name this surface'
+      help_flag :category, 'Filter by category'
+      help_flag :tag, 'Filter by a free-form tag'
+      help_flag :status, 'Filter by status: active (default), draft, archived'
+      help_flag :gaps, 'Show only requirements with an uncovered required surface (reads evidence)'
+      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'
+
       KNOWN_FLAGS = {
         project: :string,
         surface: :string,

data/lib/fp/commands/matrix.rb

@@ -13,6 +13,15 @@ module Fp
     # parity report, which is the same computation the CI gate blocks on, so what you
     # see here is what CI will decide.
     class Matrix < Base
+      help_summary 'Show the parity matrix (requirements × surfaces with evidence state)'
+      help_usage 'fp matrix --project <slug> [--surface api] [--level covered] [--csv]'
+      help_flag :project, 'Project slug (falls back to .featureparity.yml)'
+      help_flag :surface, 'Limit to one surface'
+      help_flag :level, 'Evaluate against this enforcement level (off/regression/covered/strict)'
+      help_flag :csv, 'Emit CSV instead of the ASCII table'
+      help_example 'fp matrix --project stowzilla'
+      help_example 'fp matrix --project stowzilla --csv > matrix.csv'
+
       KNOWN_FLAGS = {
         project: :string,
         surface: :string,

data/lib/fp/commands/profile.rb

@@ -5,6 +5,15 @@ module Fp
     # fp profile add|list
     # Manage named profiles for API authentication
     class Profile < Base
+      help_summary 'Manage named authentication profiles'
+      help_usage 'fp profile add <name> --api-key fp_... [--api-url URL] [--environment ENV]',
+                 'fp profile list'
+      help_flag :api_key, 'API key for the profile (starts with fp_)'
+      help_flag :api_url, 'Override API URL for the profile'
+      help_flag :environment, 'Named environment for the profile'
+      help_example 'fp profile add pari --api-key fp_...'
+      help_example 'fp --profile pari projects'
+
       KNOWN_FLAGS = {
         api_key: :string,
         api_url: :string,

data/lib/fp/commands/projects.rb

@@ -17,7 +17,27 @@ module Fp
     # or takes --yes to skip the prompt, and a non-interactive session without --yes is
     # refused rather than guessed at. The server adds its own check — only an owner (or an
     # owner's key) may delete.
+    #
+    # `edit --showroom-welcome` keeps the note at the top of the client showroom (Fizzy
+    # #1479); the per-surface cards are `fp surfaces edit --showroom-*`, and `fp showroom`
+    # previews the result.
     class Projects < Base
+      help_summary 'List, view, create, edit, and delete projects'
+      help_usage 'fp projects',
+                 'fp projects show <slug>',
+                 'fp projects create <slug> --name "..." [--description ...] [--surfaces a,b,c]',
+                 'fp projects edit <slug> [--name ...] [--description ...]',
+                 'fp projects delete <slug> [--yes]'
+      help_flag :name, 'Project name (create/edit)'
+      help_flag :description, 'Project description (create/edit)'
+      help_flag :showroom_welcome, 'Welcome note at the top of the client showroom (edit; empty clears)'
+      help_flag :showroom_welcome_file, 'Read --showroom-welcome from a file (multi-line)'
+      help_flag :surfaces, 'Comma-separated surface keys to create with the project'
+      help_flag :yes, 'Skip the typed-slug confirmation on delete'
+      help_example 'fp projects create calib-rate --name "Calib Rate" --surfaces api,web'
+      help_example 'fp projects delete calib-rate --yes'
+      help_note 'Projects land on the key owner\'s account; the same key reaches them immediately. Delete is owner-only.'
+
       CREATE_FLAGS = {
         name: :string,
         description: :string,
@@ -26,7 +46,9 @@ module Fp
 
       EDIT_FLAGS = {
         name: :string,
-        description: :string
+        description: :string,
+        showroom_welcome: :string,
+        showroom_welcome_file: :string
       }.freeze
 
       DELETE_FLAGS = {
@@ -135,14 +157,17 @@ module Fp
 
       def edit(args)
         opts, positional = parse_flags(args, EDIT_FLAGS)
-        slug = require_slug!(positional, 'fp projects edit <slug> [--name "..."] [--description "..."]')
+        slug = require_slug!(positional, 'fp projects edit <slug> [--name "..."] [--description "..."] ' \
+                                         '[--showroom-welcome "..." | --showroom-welcome-file PATH]')
 
         params = {}
         params[:name] = opts[:name] if opts[:name]
         params[:description] = opts[:description] if opts.key?(:description)
+        welcome = showroom_welcome_param(opts)
+        params[:showroom_welcome] = welcome unless welcome.nil?
 
         if params.empty?
-          output.error('Nothing to change. Pass --name and/or --description.')
+          output.error('Nothing to change. Pass --name, --description, --showroom-welcome, or --showroom-welcome-file.')
           exit 1
         end
 
@@ -161,9 +186,40 @@ module Fp
           puts
           puts "  Name:        #{record['name']}"
           puts "  Description: #{blank?(record['description']) ? '(none)' : record['description']}"
+          if params.key?(:showroom_welcome)
+            puts "  Showroom welcome: #{blank?(record['showroom_welcome']) ? '(cleared)' : ''}"
+            record['showroom_welcome'].to_s.each_line { |line| puts "    #{line.rstrip}" }
+          end
         end
       end
 
+      # The welcome note from --showroom-welcome or --showroom-welcome-file, nil when
+      # neither was passed. An empty value clears the note. A file is the sane way to
+      # write several paragraphs; the showroom keeps the line breaks.
+      def showroom_welcome_param(opts)
+        if opts.key?(:showroom_welcome) && opts.key?(:showroom_welcome_file)
+          output.error('Pass --showroom-welcome or --showroom-welcome-file, not both.')
+          exit 1
+        end
+
+        if opts.key?(:showroom_welcome_file)
+          path = opts[:showroom_welcome_file]
+          if path == true || path.to_s.strip.empty?
+            output.error('--showroom-welcome-file needs a path')
+            exit 1
+          end
+          unless File.file?(path)
+            output.error("--showroom-welcome-file: no such file '#{path}'")
+            exit 1
+          end
+          return File.read(path).strip
+        end
+
+        return nil unless opts.key?(:showroom_welcome)
+
+        opts[:showroom_welcome] == true ? '' : opts[:showroom_welcome].to_s
+      end
+
       def delete(args)
         opts, positional = parse_flags(args, DELETE_FLAGS)
         slug = require_slug!(positional, 'fp projects delete <slug> [--yes]')
@@ -276,6 +332,10 @@ module Fp
         puts
         puts "Slug:         #{project['slug']}"
         puts "Description:  #{blank?(project['description']) ? '(none)' : project['description']}"
+        unless blank?(project['showroom_welcome'])
+          puts 'Showroom welcome:'
+          project['showroom_welcome'].to_s.each_line { |line| puts "  #{line.rstrip}" }
+        end
         puts "Enforcement:  #{project['enforcement_level']}" if project['enforcement_level']
         puts "Surfaces:     #{surfaces.empty? ? '(none)' : surfaces.join(', ')}"
 

data/lib/fp/commands/propose.rb

@@ -5,6 +5,24 @@ module Fp
     # fp propose --project <slug> --slug X --name "..." --why "..." --required a,b,c --required-types unit,e2e --acceptance "..." --parent <slug> --category <cat>
     # Create a new requirement as draft
     class Propose < Base
+      help_summary 'Propose a new requirement (created as a draft; a human activates it)'
+      help_usage 'fp propose --project <slug> --slug <key> --name "..." [flags]'
+      help_flag :project, 'Project slug (falls back to .featureparity.yml)'
+      help_flag :slug, 'Initial key for the requirement', required: true
+      help_flag :name, 'Human-readable title (one product promise, present tense)', required: true
+      help_flag :why, 'One or two sentences: who needs it, the problem, the outcome'
+      help_flag :acceptance, 'Observable result + boundaries a reviewer can check'
+      help_flag :required, 'Comma-separated surfaces this requirement must be covered on'
+      help_flag :required_types, "Comma-separated test kinds each surface needs (project's vocabulary)"
+      help_flag :parent, "Parent requirement's slug (nests one level; subset of parent's surfaces)"
+      help_flag :category, 'One of: functional, non-functional, ux, performance, security, compliance'
+      help_flag :tags, 'Comma-separated free-form labels'
+      help_flag :source_type, 'Where it came from: fizzy, discord, github_issue, jira, notion, manual, ai_chat'
+      help_flag :source_url, 'URL of the originating card/issue/thread'
+      help_flag :source_context, 'Free-form note about the origin'
+      help_example 'fp propose --project stowzilla --slug print_qr --name "Print QR on container label" --why "Staff mis-type the ID without a scannable code" --required api,customer_ios --acceptance "QR scans to the container detail page"'
+      help_note 'Agents can only create drafts. A human activates it in the web app.'
+
       KNOWN_FLAGS = {
         project: :string,
         slug: :string,

data/lib/fp/commands/propose_change.rb

@@ -10,11 +10,36 @@ module Fp
     # asked for, and what prompted the ask. The requirement drops back to draft until a
     # human reviews the diff — agents never approve their own changes.
     class ProposeChange < Base
+      help_summary 'Propose a change to an existing requirement (or --removal to retire it)'
+      help_usage 'fp propose-change <slug> --project <slug> [--name/--why/--acceptance ...] --reason "..."',
+                 'fp propose-change <slug> --removal --reason "..."'
+      help_flag :project, 'Project slug (falls back to .featureparity.yml)'
+      help_flag :name, 'Proposed new title'
+      help_flag :why, 'Proposed new Why'
+      help_flag :acceptance, 'Proposed new acceptance criteria'
+      help_flag :required, 'Proposed new required surfaces (comma-separated; cannot remove a surface)'
+      help_flag :required_types, 'Proposed new required test types (comma-separated)'
+      help_flag :category, 'Proposed new category: functional, non-functional, ux, performance, security, compliance'
+      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 :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_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."
+
       KNOWN_FLAGS = {
         project: :string, name: :string, why: :string, acceptance: :string,
         required: :string, required_types: :string, category: :string, parent: :string, slug: :string,
+        no_parent: :boolean,
         reason: :string, source_type: :string, source_url: :string, source_context: :string,
-        removal: :boolean
+        removal: :boolean, withdraw: :boolean
       }.freeze
 
       VALID_CATEGORIES = %w[functional non-functional ux performance security compliance].freeze
@@ -39,17 +64,21 @@ module Fp
           exit 1
         end
 
+        validate_flag_combinations!(opts)
         validate_enums!(opts)
 
         project_id = resolve_project_id(opts[:project])
         requirement = find_requirement!(project_id, slug)
 
+        return withdraw!(requirement, slug) if opts[:withdraw]
+
         params = build_params(opts, project_id)
         removal = opts[:removal] ? true : false
 
         if !removal && params.keys.none? { |k| proposed_field?(k) }
           output.error('Nothing to propose. Pass at least one of --name/--slug/--why/--acceptance/' \
-                       '--required/--required-types/--category/--parent, or --removal to propose deletion.')
+                       '--required/--required-types/--category/--parent/--no-parent, or --removal to ' \
+                       'propose deletion.')
           exit 1
         end
 
@@ -68,6 +97,31 @@ module Fp
 
       private
 
+      # Withdraw the requirement's own open proposal (Fizzy #1492). The single-open-
+      # proposal rule means an agent that wants to *amend* what it proposed can't just
+      # open a second one — it withdraws the first (restoring the requirement to what it
+      # was) and proposes again. The server only lets the proposal's author withdraw it.
+      def withdraw!(requirement, slug)
+        change_id = requirement['pending_change_id']
+        if change_id.nil? || change_id.to_s.empty?
+          output.error("Requirement '#{slug}' has no open proposal to withdraw.")
+          exit 1
+        end
+
+        result = client.withdraw_requirement_change(requirement['id'], change_id)
+        unless result[:ok]
+          output.error(result[:error], status: result[:status])
+          exit 1
+        end
+
+        output.success(result[:data]) do
+          puts "Withdrew the open proposal for '#{slug}'."
+          puts
+          puts 'The requirement is restored to what it was before the proposal.'
+          puts 'To amend it, propose the change again with the corrected values.'
+        end
+      end
+
       # A 409 means the requirement already has an open proposal — the one-at-a-time rule
       # (two "what it was" snapshots would make a rollback ambiguous). Rather than a dead
       # end, show what the open proposal is and point at `fp comment` so the agent can
@@ -109,6 +163,20 @@ module Fp
         warn '  Fields:   ' + changes.keys.join(', ')
       end
 
+      # --parent and --no-parent contradict each other, and --withdraw is a standalone
+      # verb that ignores proposed values (Fizzy #1492).
+      def validate_flag_combinations!(opts)
+        if opts[:parent] && opts[:no_parent]
+          output.error('Pass either --parent <slug> or --no-parent, not both.')
+          exit 1
+        end
+
+        return unless opts[:withdraw] && opts[:removal]
+
+        output.error('--withdraw cancels an open proposal; it cannot be combined with --removal.')
+        exit 1
+      end
+
       def validate_enums!(opts)
         if opts[:category] && !VALID_CATEGORIES.include?(opts[:category])
           output.error("Invalid category '#{opts[:category]}'. Must be one of: #{VALID_CATEGORIES.join(', ')}")
@@ -143,6 +211,9 @@ module Fp
           params[:required_test_types] = opts[:required_types].split(',').map { |t| t.strip.downcase }.reject(&:empty?)
         end
         params[:parent_id] = resolve_parent_id(project_id, opts[:parent]) if opts[:parent]
+        # --no-parent un-nests a child back to top level: an empty parent_id. The server
+        # treats "" as "no parent" and diffs it against the current parent (Fizzy #1492).
+        params[:parent_id] = '' if opts[:no_parent]
 
         params[:removal] = true if opts[:removal]
         params[:reason] = opts[:reason] if opts[:reason]