brainiac-featureparity 0.1.0

data/lib/brainiac/plugins/featureparity/prompts.rb

@@ -0,0 +1,242 @@
+# frozen_string_literal: true
+
+module Brainiac
+  module Plugins
+    module Featureparity
+      # Prompt templates for FeatureParity agent dispatches.
+      module Prompts
+        # Channel-specific prompt for FeatureParity interactions.
+        # Injected into the agent prompt when dispatching for FP events.
+        CHANNEL = <<~PROMPT
+          ## FeatureParity Channel Rules
+
+          You're responding to a FeatureParity webhook event. FeatureParity tracks requirements
+          and their test coverage across surfaces.
+
+          ### FP Environment
+
+          This work is coming from a specific FP environment:
+          - **API URL:** {{FP_API_URL}}
+          - **Environment:** {{FP_ENVIRONMENT}}
+          - **Ephemeral:** {{FP_EPHEMERAL}}
+
+          **CRITICAL:** You MUST use `--api-url {{FP_API_URL}}` with ALL `fp` CLI commands.
+          This ensures you're reading from and writing to the correct FP instance (prod vs dev vs ephemeral).
+
+          ```bash
+          # CORRECT - always include --api-url
+          fp show <slug> --project <project> --api-url {{FP_API_URL}}
+          fp list --project <project> --api-url {{FP_API_URL}}
+          fp propose-change <slug> --project <project> --api-url {{FP_API_URL}} ...
+
+          # WRONG - will hit production FP even if you're working on dev
+          fp show <slug> --project <project>
+          ```
+
+          ### Requirement Work Workflow
+
+          When implementing a requirement from FP:
+          1. Read the requirement details to understand the spec
+          2. Implement the feature/fix in your worktree
+          3. Write tests that satisfy the acceptance criteria
+          4. Bind your tests to the requirement using `fp:<slug>` comments
+          5. Commit and push your changes
+          6. Open a PR
+
+          ### Requirement Rejection Workflow
+
+          A human has rejected a proposed change to a requirement. Your job:
+          1. Read the rejection reason to understand what's wrong
+          2. Review the requirement's current state in FP
+          3. Make the necessary code/test changes to address the feedback
+          4. Update the requirement in FP if needed using `fp` CLI commands (with --api-url!)
+          5. Push changes and update the PR
+
+          ### FP CLI Commands
+
+          Remember: ALWAYS include `--api-url {{FP_API_URL}}`
+
+          ```bash
+          fp show <slug> --project <project> --api-url {{FP_API_URL}}
+          fp list --project <project> --api-url {{FP_API_URL}}
+          fp propose-change <slug> --project <project> --api-url {{FP_API_URL}} \\
+            --title "..." --why "..." --acceptance "..."
+          ```
+
+          ### Test Binding
+
+          To link a test to a requirement, add a comment with `fp:<slug>`:
+          ```ruby
+          # fp:user-login-validation
+          test "validates email format" do
+            # ...
+          end
+          ```
+
+          ### Important Notes
+
+          - When implementing: write tests that directly exercise the acceptance criteria
+          - When reworking: address the specific rejection reason — don't make unrelated changes
+          - Keep your response focused: what you implemented/changed, what's next
+          - **Never forget `--api-url`** — using the wrong FP instance corrupts data
+        PROMPT
+
+        # The full prompt template for initial work dispatches (FP-as-source).
+        WORK_DISPATCH = <<~PROMPT
+          ## FeatureParity: Implement Requirement
+
+          You've been assigned to implement a requirement directly from FeatureParity.
+
+          ### Requirement Details
+          - **Slug:** `{{REQUIREMENT_SLUG}}`
+          - **Title:** {{REQUIREMENT_TITLE}}
+          - **Project:** {{PROJECT_KEY}}
+
+          ### FP Instance
+          - **API URL:** {{FP_API_URL}}
+          - **Environment:** {{FP_ENVIRONMENT}}
+
+          **CRITICAL:** All `fp` CLI commands MUST include `--api-url {{FP_API_URL}}`
+
+          ### Description
+          {{REQUIREMENT_DESCRIPTION}}
+
+          ### Why This Matters
+          {{REQUIREMENT_WHY}}
+
+          ### Acceptance Criteria
+          {{ACCEPTANCE_CRITERIA}}
+
+          ### Your Task
+
+          1. Read and understand the requirement fully
+          2. Implement the feature in your worktree
+          3. Write tests that exercise the acceptance criteria
+          4. Bind your tests to this requirement using `fp:{{REQUIREMENT_SLUG}}` comments
+          5. Commit your changes with a clear message referencing the requirement
+          6. Push and open a PR
+
+          Work in the worktree at: {{WORKTREE_PATH}}
+
+          When you commit, include the requirement slug in the message:
+          ```
+          Implement {{REQUIREMENT_SLUG}}: {{REQUIREMENT_TITLE}}
+          ```
+
+          To view or update the requirement in FP:
+          ```bash
+          fp show {{REQUIREMENT_SLUG}} --project {{PROJECT_KEY}} --api-url {{FP_API_URL}}
+          ```
+        PROMPT
+
+        # The full prompt template for requirement rejection dispatches.
+        REJECTION_DISPATCH = <<~PROMPT
+          ## FeatureParity: Requirement Rejection
+
+          A requirement you proposed has been rejected and needs rework.
+
+          ### Rejection Details
+          - **Requirement:** `{{REQUIREMENT_SLUG}}` — {{REQUIREMENT_TITLE}}
+          - **Rejected by:** {{ACTOR}}
+          - **Rejection note:** {{REJECTION_NOTE}}
+
+          ### FP Instance
+          - **API URL:** {{FP_API_URL}}
+          - **Environment:** {{FP_ENVIRONMENT}}
+
+          **CRITICAL:** All `fp` CLI commands MUST include `--api-url {{FP_API_URL}}`
+
+          ### Source Context
+          This requirement was proposed from: {{SOURCE_TYPE}} ({{SOURCE_URL}})
+          {{SOURCE_CONTEXT}}
+
+          ### What Changed
+          {{CHANGE_KIND}}: {{CHANGE_DETAILS}}
+
+          ### Your Task
+
+          1. Review the rejection note to understand what needs to change
+          2. Make the necessary fixes in your worktree
+          3. Update the requirement in FP if the wording/scope needs adjustment
+          4. Commit and push your changes
+          5. Summarize what you fixed and why
+
+          Work in the existing worktree at: {{WORKTREE_PATH}}
+
+          To view or update the requirement in FP:
+          ```bash
+          fp show {{REQUIREMENT_SLUG}} --api-url {{FP_API_URL}}
+          fp propose-change {{REQUIREMENT_SLUG}} --api-url {{FP_API_URL}} ...
+          ```
+        PROMPT
+
+        # Writing the tests a newly active requirement is missing (coverage.gap_detected).
+        GAP_DISPATCH = <<~PROMPT
+          ## FeatureParity: Write the Missing Tests
+
+          A requirement is now active on surfaces that have no tests yet.
+
+          ### Requirement
+          - **Slug:** `{{REQUIREMENT_SLUG}}`
+          - **Title:** {{REQUIREMENT_TITLE}}
+          - **Project:** {{PROJECT_KEY}}
+          - **Missing on:** {{MISSING_SURFACES}}
+
+          ### Acceptance Criteria
+          {{ACCEPTANCE_CRITERIA}}
+
+          ### FP Instance
+          - **API URL:** {{FP_API_URL}}
+          - **Environment:** {{FP_ENVIRONMENT}}
+
+          **CRITICAL:** All `fp` CLI commands MUST include `--api-url {{FP_API_URL}}`
+
+          ### Your Task
+
+          1. Read the requirement: `fp show {{REQUIREMENT_SLUG}} --project {{PROJECT_KEY}} --api-url {{FP_API_URL}}`
+          2. For each missing surface, write a test that exercises the acceptance criteria and mark it
+             `fp:{{REQUIREMENT_SLUG}}` (pin the surface, e.g. `fp:{{REQUIREMENT_SLUG}}@web`, when one test file serves several).
+          3. If the product doesn't do what the acceptance says, don't bend the test to fit: say so, and
+             leave a question on the requirement (`fp question {{REQUIREMENT_SLUG}} "..."`) for a human.
+          4. Run the tests, commit, push and open a PR.
+
+          Work in the worktree at: {{WORKTREE_PATH}}
+        PROMPT
+
+        # Answering a comment that tagged this agent (requirement.agent_mentioned).
+        MENTION_DISPATCH = <<~PROMPT
+          ## FeatureParity: You Were Tagged
+
+          {{COMMENT_AUTHOR}} tagged you ({{AGENT_NAME}}) in a comment on a requirement.
+
+          ### Requirement
+          - **Slug:** `{{REQUIREMENT_SLUG}}`
+          - **Title:** {{REQUIREMENT_TITLE}}
+          - **Project:** {{PROJECT_KEY}}
+
+          ### The Comment
+          {{COMMENT_BODY}}
+
+          ### FP Instance
+          - **API URL:** {{FP_API_URL}}
+          - **Environment:** {{FP_ENVIRONMENT}}
+
+          **CRITICAL:** All `fp` CLI commands MUST include `--api-url {{FP_API_URL}}`
+
+          ### Your Task
+
+          1. Read the requirement and its discussion:
+             `fp show {{REQUIREMENT_SLUG}} --project {{PROJECT_KEY}} --api-url {{FP_API_URL}}`
+             `fp comments {{REQUIREMENT_SLUG}} --project {{PROJECT_KEY}} --api-url {{FP_API_URL}}`
+          2. Do what was asked. If it is to re-check suspect tests, read the tests marked
+             `fp:{{REQUIREMENT_SLUG}}` against the current acceptance, fix them if they no longer prove it,
+             and re-report the evidence.
+          3. Reply on the requirement so they know what you did:
+             `fp comments {{REQUIREMENT_SLUG}} --project {{PROJECT_KEY}} --api-url {{FP_API_URL}} --body "..."`
+
+          Work in: {{WORKTREE_PATH}}
+        PROMPT
+      end
+    end
+  end
+end

data/lib/brainiac/plugins/featureparity/signature.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+require "openssl"
+require "base64"
+
+module Brainiac
+  module Plugins
+    module Featureparity
+      # Verifies a FeatureParity delivery (Standard Webhooks, standardwebhooks.com).
+      #
+      # FeatureParity signs every delivery with the secret of whatever it was sent to: a
+      # project webhook, or an agent key's wake-up address. Each is a "whsec_<base64>"
+      # string shown once in FeatureParity. The signature is
+      # base64(HMAC-SHA256(key, "<webhook-id>.<webhook-timestamp>.<raw body>")) where the
+      # key is the base64-decoded part after "whsec_", sent as "v1,<signature>".
+      module Signature
+        # Reject deliveries stamped more than this far from now, so a captured request
+        # can't be replayed later.
+        TOLERANCE = 300
+
+        module_function
+
+        # True when `signature` (the webhook-signature header, which may hold several
+        # space-separated "v1,..." values) matches the body under any of `secrets`.
+        def valid?(secrets:, id:, timestamp:, signature:, body:, now: Time.now.to_i)
+          return false if id.to_s.empty? || !fresh?(timestamp, now)
+
+          offered = offered_signatures(signature)
+          Array(secrets).any? do |secret|
+            expected = sign(secret, id, timestamp, body)
+            offered.any? { |sig| secure_compare(sig, expected) }
+          end
+        end
+
+        def fresh?(timestamp, now)
+          timestamp.to_s.match?(/\A\d+\z/) && (now - timestamp.to_i).abs <= TOLERANCE
+        end
+
+        # The v1 signatures in a webhook-signature header ("v1,<sig> v1,<sig>").
+        def offered_signatures(header)
+          header.to_s.split.filter_map { |part| part.split(",", 2).last if part.start_with?("v1,") }
+        end
+
+        def sign(secret, id, timestamp, body)
+          key = Base64.decode64(secret.to_s.delete_prefix("whsec_"))
+          Base64.strict_encode64(OpenSSL::HMAC.digest("SHA256", key, "#{id}.#{timestamp}.#{body}"))
+        end
+
+        def secure_compare(given, expected)
+          return false unless given.bytesize == expected.bytesize
+
+          OpenSSL.fixed_length_secure_compare(given, expected)
+        end
+      end
+
+      # Remembers what was just handled, so a retried delivery (same webhook-id) or the same
+      # event arriving twice (a project webhook and an agent's wake-up address both
+      # subscribed) dispatches one agent, not two. In memory: a restart forgets, which at
+      # worst means one repeat.
+      module Dedupe
+        TTL = 3600
+        MAX = 2000
+        @seen = {}
+        @lock = Mutex.new
+
+        module_function
+
+        # Records `key` and returns true if it was already seen within TTL.
+        def seen?(key, now: Time.now.to_f)
+          return false if key.to_s.empty?
+
+          @lock.synchronize do
+            @seen.delete_if { |_, at| now - at > TTL } if @seen.size >= MAX
+            if (at = @seen[key]) && now - at <= TTL
+              true
+            else
+              @seen[key] = now
+              false
+            end
+          end
+        end
+
+        def reset!
+          @lock.synchronize { @seen.clear }
+        end
+      end
+    end
+  end
+end

data/lib/brainiac/plugins/featureparity/version.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Brainiac
+  module Plugins
+    module Featureparity
+      VERSION = "0.1.0"
+    end
+  end
+end

data/lib/brainiac/plugins/featureparity.rb

@@ -0,0 +1,156 @@
+# frozen_string_literal: true
+
+require_relative "featureparity/version"
+require_relative "featureparity/metadata"
+require_relative "featureparity/config"
+require_relative "featureparity/prompts"
+require_relative "featureparity/signature"
+require_relative "featureparity/handlers"
+require_relative "featureparity/cli"
+
+module Brainiac
+  module Plugins
+    module Featureparity
+      # Supported webhook events from FeatureParity
+      SUPPORTED_EVENTS = %w[
+        requirement.change_rejected
+        requirement.change_approved
+        requirement.change_proposed
+        requirement.removal_proposed
+        requirement.activated
+        requirement.archived
+        requirement.updated
+        requirement.work_started
+        requirement.agent_mentioned
+        evidence.passing
+        evidence.failing
+        evidence.suspect
+        coverage.gap_detected
+      ].freeze
+
+      class << self
+        # Called by Brainiac plugin system during server startup.
+        #
+        # @param app [Sinatra::Application] The running Brainiac server
+        def register(app)
+          Config.load!
+
+          # Register channel prompt
+          Brainiac.register_channel_prompt(:featureparity, Prompts::CHANNEL)
+
+          setup_routes(app)
+
+          LOG.info "[FeatureParity] Plugin registered (webhook: /featureparity)"
+          LOG.info "[FeatureParity] Accepting webhooks from environments: #{Config.accept_environments.join(', ')}"
+        end
+
+        private
+
+        def setup_routes(app)
+          setup_webhook_route(app)
+          setup_api_routes(app)
+        end
+
+        def setup_webhook_route(app)
+          app.post "/featureparity" do
+            content_type :json
+            request.body.rewind
+            # self here is the Sinatra request, so reach the plugin by name.
+            status_code, body = Brainiac::Plugins::Featureparity.receive(request.body.read, request.env)
+            halt status_code, body
+          end
+        end
+
+        def setup_api_routes(app)
+          app.get "/api/featureparity" do
+            content_type :json
+            {
+              enabled: true,
+              api_base_url: Brainiac::Plugins::Featureparity::Config.api_base_url,
+              environment: Brainiac::Plugins::Featureparity::Config.environment,
+              accept_environments: Brainiac::Plugins::Featureparity::Config.accept_environments,
+              supported_events: SUPPORTED_EVENTS
+            }.to_json
+          end
+        end
+
+        public
+
+        # Handle one delivery: verify it, drop a repeat, check where it came from, and hand
+        # it to its event's handler. Returns [status, json body].
+        def receive(raw_body, env)
+          LOG.debug "[FeatureParity] Webhook received: #{raw_body.length} bytes" if LOG.debug?
+          refusal = verification_refusal(raw_body, env)
+          return refusal if refusal
+
+          payload = JSON.parse(raw_body)
+          screened = screen(payload)
+          return screened if screened
+
+          reload_projects!
+          reload_agent_registry!
+          dispatch_event(payload["event"], payload)
+        rescue JSON::ParserError => e
+          LOG.error "[FeatureParity] Invalid JSON: #{e.message}"
+          [400, { error: "Invalid JSON" }.to_json]
+        rescue StandardError => e
+          LOG.error "[FeatureParity] Unhandled error: #{e.message}\n#{e.backtrace&.first(5)&.join("\n")}"
+          [500, { error: e.message }.to_json]
+        end
+
+        # Signed deliveries (Standard Webhooks): with secrets configured, anything that doesn't
+        # verify is refused before it is parsed. FeatureParity retries a delivery under the
+        # same webhook-id, so a repeat is acknowledged and dropped.
+        def verification_refusal(raw_body, env)
+          delivery_id = env["HTTP_WEBHOOK_ID"]
+          secrets = Config.signing_secrets
+          if secrets.empty?
+            LOG.warn "[FeatureParity] Accepting an unverified delivery: set signing_secrets in featureparity.json"
+          elsif !Signature.valid?(secrets: secrets, id: delivery_id, timestamp: env["HTTP_WEBHOOK_TIMESTAMP"],
+                                  signature: env["HTTP_WEBHOOK_SIGNATURE"], body: raw_body)
+            LOG.warn "[FeatureParity] Refused a delivery whose signature doesn't verify (id: #{delivery_id || 'none'})"
+            return [401, { error: "invalid signature" }.to_json]
+          end
+          return [200, { status: "duplicate" }.to_json] if delivery_id && Dedupe.seen?("delivery:#{delivery_id}")
+
+          nil
+        end
+
+        # An event from an environment this instance doesn't serve, or one it doesn't handle.
+        def screen(payload)
+          event = payload["event"]
+          webhook_env = (payload["metadata"] || {})["environment"]
+          LOG.info "[FeatureParity] Received event: #{event} from environment: #{webhook_env || 'unspecified'}"
+
+          unless Config.should_accept_environment?(webhook_env)
+            LOG.info "[FeatureParity] Ignoring webhook from environment '#{webhook_env}' " \
+                     "(accepting: #{Config.accept_environments.join(', ')})"
+            return [200, { status: "ignored", reason: "environment mismatch", webhook_environment: webhook_env,
+                           accepted_environments: Config.accept_environments }.to_json]
+          end
+          return nil if SUPPORTED_EVENTS.include?(event)
+
+          LOG.info "[FeatureParity] Ignoring unsupported event: #{event}"
+          [200, { status: "ignored", reason: "unsupported event" }.to_json]
+        end
+
+        # The events that start an agent; every other supported event is acknowledged.
+        HANDLERS = {
+          "requirement.change_rejected" => :handle_change_rejected,
+          "requirement.work_started" => :handle_work_started,
+          "requirement.agent_mentioned" => :handle_agent_mentioned,
+          "coverage.gap_detected" => :handle_gap_detected
+        }.freeze
+
+        # Route an accepted event to its handler. Returns [status, json body].
+        def dispatch_event(event, payload)
+          handler = HANDLERS[event]
+          return Handlers.public_send(handler, payload) if handler
+
+          LOG.info "[FeatureParity] #{event}: #{payload.dig('data', 'slug')}"
+          [200, { status: "acknowledged", event: event }.to_json]
+        end
+      end
+    end
+  end
+end

data/lib/brainiac_featureparity.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+# Brainiac Featureparity Plugin — entry point loaded by RubyGems.
+require_relative "brainiac/plugins/featureparity"

metadata

@@ -0,0 +1,121 @@
+--- !ruby/object:Gem::Specification
+name: brainiac-featureparity
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Andy Davis
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: brainiac
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.1.8
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.1.8
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.25'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.25'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.75'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.75'
+- !ruby/object:Gem::Dependency
+  name: rubocop-performance
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.25'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.25'
+description: FeatureParity integration for Brainiac — starts the agent picked for
+  a requirement, answers comments that tag it, writes missing tests, and reworks rejected
+  proposals. Verifies FeatureParity's signed deliveries.
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- lib/brainiac/plugins/featureparity.rb
+- lib/brainiac/plugins/featureparity/cli.rb
+- lib/brainiac/plugins/featureparity/config.rb
+- lib/brainiac/plugins/featureparity/handlers.rb
+- lib/brainiac/plugins/featureparity/metadata.rb
+- lib/brainiac/plugins/featureparity/prompts.rb
+- lib/brainiac/plugins/featureparity/signature.rb
+- lib/brainiac/plugins/featureparity/version.rb
+- lib/brainiac_featureparity.rb
+homepage: https://github.com/stowzilla/brainiac-featureparity
+licenses:
+- MIT
+metadata:
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.4'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: FeatureParity plugin for Brainiac
+test_files: []