feature_machine 0.1.0

data/lib/feature_machine/configuration.rb

@@ -0,0 +1,165 @@
+module FeatureMachine
+  # Everything the engine needs from its host, as plain values and callables.
+  # Set it once in config/initializers/feature_machine.rb:
+  #
+  #   FeatureMachine.configure do |config|
+  #     config.current_user     = ->(request) { ... }      # the host's user, or nil
+  #     config.admin            = ->(user) { user.admin? } # may this user triage?
+  #     config.authenticate_api = ->(token) { ... }        # bearer token -> credential, or nil
+  #     config.product_name     = "My App"
+  #     config.token_help_url   = "https://my.app/token"
+  #   end
+  #
+  # A credential is any object answering `user` and `allows?(scope)` for the
+  # scopes in FeatureMachine::SCOPES. The host's token model never has to be
+  # known to the engine.
+  class Configuration
+    attr_accessor :user_class, :current_user, :admin, :authenticate_api, :session_auth,
+                  :product_name, :token_help_url, :protected_resource_url,
+                  :embedding_model, :drafter_model, :drafter_provider, :drafter_fallbacks,
+                  :judgment_model, :judgment_provider, :roadmap_path, :bug_reports_path, :new_bug_report_path,
+                  :admin_nav_partial, :user_label, :admin_triage_path, :layout,
+                  :on_status_change, :parent_controller, :admin_parent_controller,
+                  :api_parent_controller, :sign_in_path, :flash_in_pages,
+                  :default_stylesheet
+
+    # The engine's own pages, linked by default. A host that draws its own
+    # roadmap or bug board points these at it instead, or sets nil to drop the
+    # link. respond_to? keeps a link out when its route isn't drawn.
+    DEFAULT_ROADMAP_PATH = lambda do |view, work_item = nil|
+      view.roadmap_path(anchor: (view.dom_id(work_item) if work_item)) if view.respond_to?(:roadmap_path)
+    end
+    DEFAULT_BUG_REPORTS_PATH     = ->(view) { view.bug_reports_path if view.respond_to?(:bug_reports_path) }
+    DEFAULT_NEW_BUG_REPORT_PATH  = ->(view) { view.new_bug_report_path if view.respond_to?(:new_bug_report_path) }
+    DEFAULT_ADMIN_TRIAGE_PATH    = ->(view) { view.admin_triage_path if view.respond_to?(:admin_triage_path) }
+    # Where a signed-out visitor to an engine page is sent, given the
+    # controller. Rails' authentication generator draws new_session_path.
+    DEFAULT_SIGN_IN_PATH         = ->(controller) { controller.new_session_path if controller.respond_to?(:new_session_path) }
+
+    def initialize
+      @user_class             = "User"
+      @current_user           = ->(_request) { nil }
+      @admin                  = ->(user) { user.respond_to?(:admin?) && user.admin? }
+      @authenticate_api       = nil
+      @session_auth           = true
+      @product_name           = "this app"
+      @token_help_url         = nil
+      @protected_resource_url = nil
+      @embedding_model        = nil
+      @drafter_model          = nil
+      @drafter_provider       = nil
+      @drafter_fallbacks      = []
+      @judgment_model         = nil
+      @judgment_provider      = nil
+      @roadmap_path           = DEFAULT_ROADMAP_PATH
+      @bug_reports_path       = DEFAULT_BUG_REPORTS_PATH
+      @new_bug_report_path    = DEFAULT_NEW_BUG_REPORT_PATH
+      @admin_nav_partial      = nil
+      @user_label             = ->(user) { "user ##{user.id}" }
+      @admin_triage_path      = DEFAULT_ADMIN_TRIAGE_PATH
+      @product_blurb          = nil
+      @layout                 = nil
+      @on_status_change       = nil
+      @parent_controller      = "ApplicationController"
+      @admin_parent_controller = nil
+      @api_parent_controller  = "ActionController::API"
+      @sign_in_path           = DEFAULT_SIGN_IN_PATH
+      @flash_in_pages         = true
+      # Inline the engine's cn-* styles on every page. They sit in a CSS
+      # layer, so a host's own cn-* rules win; a host with a full cn design
+      # system can still turn them off.
+      @default_stylesheet     = true
+    end
+
+    # The classes engine controllers inherit from, named as strings so the
+    # initializer never autoloads app code. Pages inherit the host's
+    # ApplicationController (its layout, its auth filters); admin pages inherit
+    # admin_parent_controller, falling back to the same; the API inherits
+    # ActionController::API unless the host has its own base for error shape,
+    # rate-limit headers and the like. The engine adds its own admin check and
+    # token auth on top of whichever it gets.
+    def admin_parent_controller
+      @admin_parent_controller || parent_controller
+    end
+
+    # The layout engine pages render through. nil (the default) means the
+    # host's own: engine controllers inherit the host's ApplicationController
+    # and so its layout, nav and stylesheets. A host with no layout of its own
+    # (or one it doesn't want the engine in) names one, e.g. "feature_machine"
+    # for the engine's minimal standalone shell. `.md` responses never use it.
+
+    # One line the drafter uses to describe the product to the model, e.g.
+    # "My App (a todo list with an API for agents)". Falls back to product_name
+    # so a host that sets nothing still gets a truthful, if terse, prompt.
+    attr_writer :product_blurb
+
+    def product_blurb
+      @product_blurb.to_s.empty? ? product_name : @product_blurb
+    end
+
+    # Links the engine's views offer: a lambda given the view context plus any
+    # record the link is about, returning a path, or nil to leave the link out.
+    # They default to the engine's own pages (DEFAULT_*_PATH); a host with its
+    # own roadmap or bug board points them there.
+    #
+    #   admin_triage_path:   ->(view) { ... }                  the host's triage inbox
+    #   roadmap_path:        ->(view, work_item = nil) { ... } the roadmap, anchored on an item if given
+    #   bug_reports_path:    ->(view) { ... }                  the host's bug board
+    #   new_bug_report_path: ->(view) { ... }                  where to file a bug
+    def host_path(name, view, *args)
+      callable = public_send(name)
+      callable&.call(view, *args)
+    end
+
+    # The host's own admin navigation, rendered at the top of every engine
+    # admin page when set (a partial path such as "admin/nav"); nil renders
+    # nothing. The engine never names a host route or page itself.
+    def admin_nav_partial?
+      !admin_nav_partial.nil?
+    end
+
+    # How a requester is named wherever the engine shows one (admin pages,
+    # specs handed to agents). The host knows its user model; the engine
+    # only knows it has an id.
+    def label_for(user)
+      user_label.call(user)
+    end
+
+    # Any RubyLLM embedding model name. nil turns embeddings off: requests and
+    # work items are never embedded, and triage shows a flat newest-first list
+    # instead of similarity buckets. pgvector only decides where vectors live.
+    def embeddings?
+      !embedding_model.nil?
+    end
+
+    # Any RubyLLM chat model name, with an optional explicit provider and an
+    # ordered list of fallback models for when it is unavailable. nil turns the
+    # model off: forming a work item still works, the draft is a plain digest
+    # of the requests instead of a written specification.
+    def drafter?
+      !drafter_model.nil?
+    end
+
+    # A RubyLLM model whose provider does structured judgments (OpenAI,
+    # Ollama, or TypeSafe's Jev, which OpenRouter also serves). nil turns judging off: triage shows the
+    # similarity buckets unranked, with no bug/duplicate/clarity flags.
+    # judgment_provider names the provider outright, for a model id the
+    # registry doesn't know, such as one on a local Jev-compatible server
+    # (:typesafe with RubyLLM's typesafe_api_base pointed at it).
+    def judge?
+      !judgment_model.nil?
+    end
+
+    # The engine never trusts a credential's own answer for the one scope with
+    # teeth: before any maintainer action it asks the host again whether the
+    # user may triage. A host that misconfigures its tokens still can't hand
+    # the queue to a customer.
+    def admin?(user)
+      !!(user && admin.call(user))
+    end
+
+    def user_for(request)
+      current_user.call(request)
+    end
+  end
+end

data/lib/feature_machine/engine.rb

@@ -0,0 +1,34 @@
+module FeatureMachine
+  # The engine's Rails hook: installs the two auth middlewares on the host's
+  # stack once its initializers have run, and adds the engine's prompts to
+  # RubyLLM's search path. Both middlewares are no-ops until configured
+  # (Bearer without `authenticate_api`, Session with `session_auth = false`),
+  # so installing is unconditional and tests can flip the configuration
+  # without rebuilding the stack.
+  #
+  # Models, controllers, views, jobs, services, prompts and the MCP tools live
+  # in the engine's app/. It is not isolated: its routes are drawn into the
+  # host's own route set by the feature_machine_routes macro (see Routes), so
+  # its pages use the host's unprefixed route helpers.
+  class Engine < ::Rails::Engine
+    # Without isolate_namespace the name would default to
+    # "feature_machine_engine", and so would the install:migrations task.
+    engine_name "feature_machine"
+
+    # The engine ships its three migrations in db/migrate. A new host copies
+    # them with `bin/rails feature_machine:install:migrations`. A host that already
+    # has copies with the same class names gets all three skipped, and its
+    # schema.rb doesn't change. Nothing adds the engine's path
+    # to the host's migrations_paths, so they never run twice.
+    initializer "feature_machine.auth_middleware", after: :load_config_initializers do |app|
+      app.middleware.use FeatureMachine::Auth::Bearer
+      app.middleware.use FeatureMachine::Auth::Session
+    end
+
+    # RubyLLM::Prompt only looks in Rails.root/app/prompts by default. The host
+    # root stays first, so a host app can override any engine prompt.
+    initializer "feature_machine.prompts" do
+      RubyLLM::Prompt.roots << root.join("app/prompts")
+    end
+  end
+end

data/lib/feature_machine/judge_calibration.rb

@@ -0,0 +1,85 @@
+require "yaml"
+
+module FeatureMachine
+  # Runs the mutation calibration cases (calibration/judge_cases.yml)
+  # through a judge and says which ones it got wrong. Three checks per case:
+  #
+  #   base        lands on base.expect
+  #   equivalent  stays within the drift threshold of the base answer
+  #   faulty      lands on faulty.expect
+  #
+  # The judge is anything that answers `call(text, context)` with a hash-like
+  # judgment (`fetch(question)` returning an answer with #probability or
+  # #score). The default calls FeatureMachine::Judge against the configured
+  # judgment_model, so `rake feature_machine:calibrate_judge` costs real tokens.
+  # Tests pass a fake.
+  class JudgeCalibration
+    CASES_PATH = File.expand_path("calibration/judge_cases.yml", __dir__)
+    SCORE_LEVELS = %w[Low Mid High].freeze
+    Request = Struct.new(:kind, :title, :description, keyword_init: true)
+    Check = Struct.new(:case_id, :variant, :ok, :detail, keyword_init: true)
+
+    def self.load(path = CASES_PATH)
+      new(YAML.safe_load_file(path))
+    end
+
+    def initialize(file, judge: nil)
+      @file = file
+      @judge = judge || ->(text, open_items) { Judge.judge_text(text, open_items) }
+    end
+
+    def run
+      @file.fetch("cases").flat_map { |c| check(c) }
+    end
+
+    private
+
+    def check(c)
+      question = c.fetch("question").to_sym
+      base = answer(c["base"], question)
+      equivalent = answer(c["equivalent"], question)
+      faulty = answer(c["faulty"], question)
+
+      [
+        Check.new(case_id: c["id"], variant: "base", ok: label(base, question) == c["base"]["expect"],
+                  detail: "#{format(base)} (want #{c["base"]["expect"]})"),
+        Check.new(case_id: c["id"], variant: "equivalent", ok: (base - equivalent).abs <= max_drift(question),
+                  detail: "#{format(equivalent)} vs base #{format(base)} (max drift #{max_drift(question)})"),
+        Check.new(case_id: c["id"], variant: "faulty", ok: label(faulty, question) == c["faulty"]["expect"],
+                  detail: "#{format(faulty)} (want #{c["faulty"]["expect"]})")
+      ]
+    end
+
+    # A probability as a Float, or a score as a level index (Integer).
+    def answer(variant, question)
+      request = Request.new(kind: variant["kind"], title: variant["title"], description: variant["description"])
+      result = @judge.call(Judge.request_text(request), context).fetch(question)
+      score_question?(question) ? result.score.round : result.probability
+    end
+
+    def label(value, question)
+      return SCORE_LEVELS.fetch(value) if score_question?(question)
+
+      value >= 0.5 ? "high" : "low"
+    end
+
+    def max_drift(question)
+      key = score_question?(question) ? "score_drift" : "probability_drift"
+      @file.fetch("thresholds").fetch(key)
+    end
+
+    def score_question?(question) = question == :clarity
+
+    def format(value) = value.is_a?(Integer) ? SCORE_LEVELS.fetch(value) : value.round(2).to_s
+
+    def context
+      @context ||= Judge.items_text(@file.fetch("open_items").map { |title| title_item(title) })
+    end
+
+    # "[feature] Pin articles..." back into the kind/title shape items_text reads.
+    def title_item(line)
+      kind, title = line.match(/\A\[(\w+)\] (.+)\z/).captures
+      Request.new(kind: kind, title: title)
+    end
+  end
+end

data/lib/feature_machine/routes.rb

@@ -0,0 +1,61 @@
+require "action_dispatch/routing/mapper"
+
+module FeatureMachine
+  # The engine's routes, drawn into the host's own route set rather than
+  # mounted. The engine isn't isolated, so its
+  # controllers and views use the host's unprefixed helpers
+  # (feature_requests_path, admin_work_items_path); a mount would move those
+  # onto an engine proxy. The host calls the macro once per scope, inside the
+  # namespace that scope belongs to:
+  #
+  #   feature_machine_routes :web          # top level, before any catch-all
+  #   namespace :admin do
+  #     feature_machine_routes :admin
+  #   end
+  #   namespace :api, defaults: { format: :json } do
+  #     feature_machine_routes :api
+  #   end
+  #   feature_machine_routes :mcp          # POST /mcp, for agents
+  #
+  # Paths and helper names match what the first host drew by hand, so URLs
+  # don't move. The macro now also draws bug reports, the roadmap, triage,
+  # attachments and their APIs: a host that still draws any of those itself
+  # must drop its own, or Rails refuses the duplicate route name at boot. A
+  # host that already serves MCP skips :mcp and mounts FeatureMachine::Mcp's
+  # tools in its own server instead.
+  module Routes
+    SCOPES = %i[ web admin api mcp ].freeze
+
+    def feature_machine_routes(scope)
+      case scope
+      when :web
+        resources :feature_requests, only: [ :index, :new, :create ], path: "feature-requests", controller: "feature_machine/feature_requests"
+        resources :bug_reports, only: [ :index, :new, :create ], path: "bug-reports", controller: "feature_machine/bug_reports"
+        get "/roadmap", to: "feature_machine/roadmap#show", as: :roadmap, format: false
+      when :admin
+        resource :triage, only: [ :show ], controller: "/feature_machine/admin/triage"
+        resources :attachments, only: [ :create ], controller: "/feature_machine/admin/attachments"
+        resources :feature_requests, only: [ :update ], controller: "/feature_machine/admin/feature_requests"
+        resources :work_items, controller: "/feature_machine/admin/work_items" do
+          member { post :draft }
+          resources :relations, only: [ :create, :destroy ], controller: "/feature_machine/admin/work_item_relations"
+        end
+      when :api
+        resources :feature_requests, only: [ :index, :create ], controller: "feature_machine/feature_requests"
+        resources :work_items, only: [ :index, :show, :update ], controller: "feature_machine/work_items"
+        resources :bug_reports, only: [ :index, :create ], controller: "feature_machine/bug_reports"
+        resource :roadmap, only: [ :show ], controller: "feature_machine/roadmaps"
+        namespace :maintainer do
+          resources :feature_requests, only: [ :index ], controller: "/api/feature_machine/maintainer/feature_requests"
+        end
+      when :mcp
+        post "/mcp", to: "feature_machine/mcp#handle", as: :feature_machine_mcp
+        get  "/mcp", to: "feature_machine/mcp#reject_get"
+      else
+        raise ArgumentError, "feature_machine_routes scope must be one of #{SCOPES.inspect}, got #{scope.inspect}"
+      end
+    end
+  end
+end
+
+ActionDispatch::Routing::Mapper.include(FeatureMachine::Routes)

data/lib/feature_machine/version.rb

@@ -0,0 +1,3 @@
+module FeatureMachine
+  VERSION = "0.1.0".freeze
+end

data/lib/feature_machine.rb

@@ -0,0 +1,57 @@
+# feature_machine: the feature-request -> triage -> work-item -> agent loop,
+# packaged as a Rails engine.
+#
+# The gem's entry point. The host loads it from its Gemfile, so
+# Bundler.require runs it before the application class exists and the
+# namespace is there before Zeitwerk descends into app/*/feature_machine/.
+# This file and lib/feature_machine/ are the engine's configuration and host
+# seams.
+#
+# Require the runtime gems the engine names at boot (the prompts initializer
+# touches RubyLLM::Prompt). A host may load them already; a fresh
+# host that only adds feature_machine doesn't, and fails to boot without these.
+require "ruby_llm"
+require "neighbor"
+require "jbuilder"
+require "mcp"
+require_relative "feature_machine/version"
+require_relative "feature_machine/configuration"
+require_relative "feature_machine/auth"
+require_relative "feature_machine/engine"
+require_relative "feature_machine/routes"
+
+module FeatureMachine
+  # The Rack env key every engine controller and MCP tool reads its credential
+  # from. The middlewares in FeatureMachine::Auth set it; a host with its own
+  # authentication middleware can set it directly instead.
+  ENV_KEY = "feature_machine.credential".freeze
+
+  # The three scopes the engine asks about. A host's token model may know
+  # twenty; the engine only ever asks these.
+  READ       = "read".freeze
+  WRITE      = "write".freeze
+  MAINTAINER = "maintainer".freeze
+  SCOPES     = [ READ, WRITE, MAINTAINER ].freeze
+
+  class << self
+    def config
+      @config ||= Configuration.new
+    end
+
+    def configure
+      yield config
+      config
+    end
+
+    # The engine's default cn-* stylesheet (app/assets/feature_machine/default.css),
+    # read once. Engine pages inline it unless config.default_stylesheet is false.
+    def default_stylesheet
+      @default_stylesheet ||= Engine.root.join("app/assets/feature_machine/default.css").read.freeze
+    end
+
+    # Tests only: forget the host's configuration.
+    def reset_config!
+      @config = nil
+    end
+  end
+end

data/lib/generators/feature_machine/install/install_generator.rb

@@ -0,0 +1,76 @@
+require "rails/generators"
+
+module FeatureMachine
+  module Generators
+    # rails g feature_machine:install
+    #
+    # Writes config/initializers/feature_machine.rb with every knob in
+    # FeatureMachine::Configuration, set to its default or commented out, and
+    # says what to run next. Also draws the engine's routes into
+    # config/routes.rb. Migrations come from the engine's own
+    # install:migrations task so a host can re-run it after upgrades.
+    class InstallGenerator < Rails::Generators::Base
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Creates config/initializers/feature_machine.rb for the feature_machine engine."
+
+      def copy_initializer
+        template "initializer.rb", "config/initializers/feature_machine.rb"
+      end
+
+      # Rails' authentication generator redirects to root_url after sign-in,
+      # and a fresh `rails new` has no root route, so the first login 500s.
+      # Not the engine's bug, but every first-time installer hits it.
+      def check_root_route
+        routes = File.join(destination_root, "config/routes.rb")
+        return unless rails_authentication? && File.exist?(routes)
+        return if File.read(routes).match?(/^\s*root\b/)
+
+        say_status :warn, "config/routes.rb has no root route; Rails' sign-in redirects to root_url and will 500 until you add one", :yellow
+      end
+
+      # The engine's routes are drawn into the host's route set (see
+      # FeatureMachine::Routes), so the generator adds the four macro calls
+      # rather than a mount line. Skipped if the host already calls the macro.
+      def add_routes
+        routes = File.join(destination_root, "config/routes.rb")
+        unless File.exist?(routes)
+          say_status :skip, "config/routes.rb not found; add the feature_machine_routes calls yourself", :yellow
+          return
+        end
+        return say_status(:identical, "feature_machine_routes in config/routes.rb", :blue) if File.read(routes).include?("feature_machine_routes")
+
+        route <<~RUBY
+          feature_machine_routes :web
+          namespace :admin do
+            feature_machine_routes :admin
+          end
+          namespace :api, defaults: { format: :json } do
+            feature_machine_routes :api
+          end
+          feature_machine_routes :mcp
+        RUBY
+      end
+
+      def show_next_steps
+        say <<~MSG
+
+          feature_machine is configured in config/initializers/feature_machine.rb.
+          Next:
+            bin/rails feature_machine:install:migrations
+            bin/rails db:migrate
+          Then check current_user and admin, and set authenticate_api for your app.
+          Signed-in users get /feature-requests, /bug-reports and /roadmap;
+          admins get /admin/triage and /admin/work_items; agents get /api and /mcp.
+        MSG
+      end
+
+      private
+        # `bin/rails generate authentication` writes app/models/session.rb and
+        # a signed session_id cookie; that's the convention we key off.
+        def rails_authentication?
+          File.exist?(File.join(destination_root, "app/models/session.rb"))
+        end
+    end
+  end
+end

data/lib/generators/feature_machine/install/templates/initializer.rb

@@ -0,0 +1,99 @@
+# What the feature_machine engine needs from this app. Every setting is shown
+# with its default; the first three are the ones a real host must change.
+# Lambdas stay lazy: initializers may not autoload app constants.
+FeatureMachine.configure do |config|
+  # The user model the engine's requests and work items belong to.
+  config.user_class   = "User"
+
+<% if rails_authentication? -%>
+  # The signed-in user for a request, or nil. This app has Rails'
+  # authentication generator (app/models/session.rb), so the session cookie
+  # it sets answers the question.
+  config.current_user = ->(request) { Session.find_by(id: request.cookie_jar.signed[:session_id])&.user }
+<% else -%>
+  # The signed-in user for a request, or nil. The default treats everyone as
+  # signed out, so nothing is readable until this is set.
+  config.current_user = ->(_request) { nil }
+<% end -%>
+
+  # May this user triage requests and manage work items?
+  config.admin        = ->(user) { user.respond_to?(:admin?) && user.admin? }
+
+  # Bearer token -> credential (any object answering `user` and
+  # `allows?(scope)` for "read", "write" and "maintainer"), or nil. Without
+  # it the API takes no tokens and maintainer endpoints refuse everything.
+  # config.authenticate_api = ->(token) { ApiToken.authenticate(token) }
+
+  # Signed-in users may use the API through their session cookie (writes are
+  # CSRF-checked). Turn off for a token-only API.
+  config.session_auth = true
+
+  # How the engine names this app in its pages and in the drafter's prompt.
+  config.product_name = "<%= Rails.application.class.module_parent_name.underscore.humanize %>"
+  # config.product_blurb = "My App (a todo list with an API for agents)"
+
+  # Where users get an API token, and the OAuth protected-resource metadata
+  # URL sent on 401s. nil leaves them out.
+  # config.token_help_url         = "https://example.com/token"
+  # config.protected_resource_url = "https://example.com/.well-known/oauth-protected-resource"
+
+  # Any RubyLLM embedding model groups similar requests; nil turns embeddings
+  # off and triage falls back to a flat newest-first list.
+  # config.embedding_model = "text-embedding-3-small"
+
+  # Any RubyLLM chat model drafts work-item specs; nil drafts a plain digest.
+  # config.drafter_model     = "gpt-4.1-mini"
+  # config.drafter_provider  = :openai
+  # config.drafter_fallbacks = []
+
+  # A RubyLLM chat model ranks untriaged requests (bug? duplicate? clear?);
+  # nil keeps triage unranked. It needs a provider with structured judgments:
+  # OpenAI, Ollama, or TypeSafe ("jev-latest"). With only an OpenRouter key,
+  # use "jev-latest" and set RubyLLM's typesafe_api_base to
+  # "https://openrouter.ai/api" and typesafe_api_key to that key. For a local
+  # Jev-compatible server, point typesafe_api_base at it and name the provider
+  # so the server's own model id resolves.
+  # config.judgment_model    = nil
+  # config.judgment_provider = nil   # e.g. :typesafe
+
+  # The layout engine pages render through. nil uses this app's own; set
+  # "feature_machine" for the engine's minimal standalone shell.
+  # config.layout = nil
+
+  # Engine pages show their own notices ("Thanks. Its status will update
+  # here."), since a new app's layout doesn't render flash. Turn this off if
+  # yours does, or they'll show twice.
+  # config.flash_in_pages = true
+
+  # Engine pages inline default styles for their cn-* classes, in a CSS layer
+  # so your own cn-* rules win. Turn off if your design system styles them all.
+  # config.default_stylesheet = true
+
+  # What engine controllers inherit from, as class names. Pages and admin
+  # pages get this app's ApplicationController (its layout and auth filters);
+  # the API gets ActionController::API unless you have a base of your own.
+  # config.parent_controller       = "ApplicationController"
+  # config.admin_parent_controller = "ApplicationController"
+  # config.api_parent_controller   = "ActionController::API"
+
+  # Where a signed-out visitor to an engine page goes, given the controller.
+  # The default finds new_session_path (Rails' authentication generator);
+  # nil answers 401.
+  # config.sign_in_path = ->(controller) { controller.new_session_path }
+
+  # The engine links its own roadmap, bug reports and triage pages. Point a
+  # lambda at your own page instead, or set nil to drop the link.
+  # config.roadmap_path        = ->(view, work_item = nil) { view.roadmap_path }
+  # config.bug_reports_path    = ->(view) { view.bug_reports_path }
+  # config.new_bug_report_path = ->(view) { view.new_bug_report_path }
+  # config.admin_triage_path   = ->(view) { view.admin_triage_path }
+
+  # This app's admin nav partial, rendered atop engine admin pages, and how a
+  # requester is named in them and in what agents read.
+  # config.admin_nav_partial = "admin/nav"
+  # config.user_label        = ->(user) { "user ##{user.id}" }
+
+  # Called with the request after each committed status change, e.g. to tell
+  # the requester. Keep it fast (enqueue a job); nil does nothing.
+  # config.on_status_change = ->(request) { StatusNoteJob.perform_later(request.id) }
+end

data/lib/tasks/feature_machine_calibration.rake

@@ -0,0 +1,17 @@
+# Live-model calibration for FeatureMachine::Judge (opt-in, never in CI: it
+# spends tokens on config.judgment_model). Fails if an equivalent mutant moves
+# an answer past threshold, or a faulty mutant doesn't move it.
+namespace :feature_machine do
+  desc "Run the Judge mutation calibration cases against config.judgment_model"
+  task calibrate_judge: :environment do
+    abort "feature_machine.judgment_model is nil; nothing to calibrate." unless FeatureMachine.config.judge?
+
+    require "feature_machine/judge_calibration"
+    checks = FeatureMachine::JudgeCalibration.load.run
+    checks.each { |c| puts "#{c.ok ? "ok  " : "FAIL"} #{c.case_id} #{c.variant}: #{c.detail}" }
+
+    failed = checks.reject(&:ok)
+    puts "\n#{checks.size - failed.size}/#{checks.size} checks held on #{FeatureMachine.config.judgment_model}."
+    abort "#{failed.size} calibration checks failed." if failed.any?
+  end
+end

data/lib/tasks/feature_machine_embeddings.rake

@@ -0,0 +1,10 @@
+namespace :feature_machine do
+  desc "Embed requests filed before config.embedding_model was set"
+  task embed_requests: :environment do
+    abort "feature_machine.embedding_model is nil; nothing to embed." unless FeatureMachine.config.embeddings?
+
+    filled = FeatureMachine::Request.backfill_embeddings
+    missing = FeatureMachine::Request.unembedded.count
+    puts "Embedded #{filled}; #{missing} still missing#{' (see the log for why)' if missing.positive?}."
+  end
+end