feature_machine 0.1.0

data/app/controllers/feature_machine/admin/base_controller.rb

@@ -0,0 +1,16 @@
+# Every engine admin page. Anyone config.admin doesn't vouch for gets a 404
+# rather than a 403, so the admin surface doesn't advertise itself. The
+# parent is the host's (config.admin_parent_controller), so its layout and
+# any admin filters of its own still apply.
+class FeatureMachine::Admin::BaseController < FeatureMachine.config.admin_parent_controller.constantize
+  include FeatureMachine::CurrentUser
+  include FeatureMachine::EngineLayout
+
+  before_action :require_feature_machine_admin
+
+  private
+
+  def require_feature_machine_admin
+    head :not_found unless FeatureMachine.config.admin?(feature_machine_user)
+  end
+end

data/app/controllers/feature_machine/admin/feature_requests_controller.rb

@@ -0,0 +1,24 @@
+# Per-request triage decisions: move a request into or out of a work item,
+# decline it with a note, or reopen it.
+class FeatureMachine::Admin::FeatureRequestsController < FeatureMachine::Admin::BaseController
+  def update
+    feature_request = ::FeatureMachine::Request.find(params[:id])
+    attributes = params.expect(feature_request: [ :work_item_id, :status, :progress_note ])
+    # Which statuses an admin may set lives on the model.
+    return head :unprocessable_entity unless feature_request.update(attributes)
+
+    redirect_back fallback_location: admin_triage_path, notice: notice_for(feature_request)
+  end
+
+  private
+
+  def notice_for(feature_request)
+    if feature_request.work_item
+      "Attached to \"#{feature_request.work_item.title}\"."
+    elsif feature_request.declined?
+      "Request declined."
+    else
+      "Request is back in triage."
+    end
+  end
+end

data/app/controllers/feature_machine/admin/triage_controller.rb

@@ -0,0 +1,9 @@
+# The triage inbox: untriaged requests, bucketed by similarity and ranked by
+# how many different people asked.
+class FeatureMachine::Admin::TriageController < FeatureMachine::Admin::BaseController
+  def show
+    @buckets = ::FeatureMachine::TriageBuckets.new.call
+    @request_count = @buckets.sum { |bucket| bucket.requests.size }
+    @work_items = ::FeatureMachine::WorkItem.active.order(:title)
+  end
+end

data/app/controllers/feature_machine/admin/work_item_relations_controller.rb

@@ -0,0 +1,24 @@
+class FeatureMachine::Admin::WorkItemRelationsController < FeatureMachine::Admin::BaseController
+  before_action :set_work_item
+
+  def create
+    relation = @work_item.outgoing_relations.build(params.expect(work_item_relation: [ :to_work_item_id, :kind ]))
+
+    if relation.save
+      redirect_to admin_work_item_path(@work_item), notice: "Linked."
+    else
+      redirect_to admin_work_item_path(@work_item), alert: relation.errors.full_messages.to_sentence
+    end
+  end
+
+  def destroy
+    @work_item.relations.find(params[:id]).destroy!
+    redirect_to admin_work_item_path(@work_item), notice: "Link removed."
+  end
+
+  private
+
+  def set_work_item
+    @work_item = ::FeatureMachine::WorkItem.find(params[:work_item_id])
+  end
+end

data/app/controllers/feature_machine/admin/work_items_controller.rb

@@ -0,0 +1,88 @@
+class FeatureMachine::Admin::WorkItemsController < FeatureMachine::Admin::BaseController
+  before_action :set_work_item, only: %i[show edit update destroy draft]
+
+  def index
+    grouped = ::FeatureMachine::WorkItem.includes(:feature_requests).newest_first.group_by(&:status)
+    @work_items = ::FeatureMachine::WorkItem::ADMIN_ORDER.index_with { |status| grouped.fetch(status, []) }
+  end
+
+  # The hand-off view. `.md` is the same spec as a document to paste into an
+  # issue tracker or hand to whoever builds it.
+  def show
+    respond_to do |format|
+      format.html
+      format.md { render layout: false }
+    end
+  end
+
+  def new
+    @work_item = ::FeatureMachine::WorkItem.new(kind: params[:kind].presence_in(::FeatureMachine::WorkItem.kinds.keys) || "feature")
+  end
+
+  # Two ways in: the blank form, or "form a work item" on a triage bucket,
+  # which arrives with request_ids and drafts the whole spec from them.
+  def create
+    requests = ::FeatureMachine::Request.untriaged.where(id: params[:request_ids]).includes(:user).oldest_first
+    return create_from_requests(requests) if requests.any?
+
+    @work_item = ::FeatureMachine::WorkItem.new(work_item_params)
+    if @work_item.save
+      redirect_to edit_admin_work_item_path(@work_item), notice: "Work item created."
+    else
+      render :new, status: :unprocessable_entity
+    end
+  end
+
+  def edit
+  end
+
+  # Also serves the one-click review decisions on the show page (ship it,
+  # send it back), which post just a status.
+  def update
+    if @work_item.update(work_item_params)
+      redirect_to admin_work_item_path(@work_item), notice: @work_item.saved_change_to_status? ? "Now #{helpers.work_item_status_label(@work_item.status).downcase}." : "Work item saved."
+    else
+      render :edit, status: :unprocessable_entity
+    end
+  end
+
+  def destroy
+    @work_item.destroy!
+    redirect_to admin_work_items_path, notice: "Work item deleted. Its requests are back in triage."
+  end
+
+  # Rewrites the spec from the item's requests. Always lands on the edit
+  # form: a draft is something to review, never something to publish as-is.
+  def draft
+    draft = ::FeatureMachine::WorkItemDrafter.new(@work_item.feature_requests.includes(:user).oldest_first, kind: @work_item.kind).call
+
+    if @work_item.update(draft.attributes)
+      redirect_to edit_admin_work_item_path(@work_item),
+        notice: draft.from_model? ? "Spec drafted from the requests. Review it before planning." : "The model was unavailable, so the spec is a plain digest of the requests."
+    else
+      redirect_to edit_admin_work_item_path(@work_item), alert: "Draft could not be saved: #{@work_item.errors.full_messages.to_sentence}"
+    end
+  end
+
+  private
+
+  # The draft is written by the model from user text, so it always opens in
+  # the editor as a private draft; planning it is a separate, human step.
+  def create_from_requests(requests)
+    draft = ::FeatureMachine::WorkItemDrafter.new(requests).call
+    work_item = ::FeatureMachine::WorkItem.create!(draft.attributes.merge(kind: requests.first.kind))
+    requests.each { |request| request.update!(work_item: work_item) }
+
+    formed = "Work item formed from #{helpers.pluralize(requests.size, 'request')}."
+    redirect_to edit_admin_work_item_path(work_item),
+      notice: draft.from_model? ? "#{formed} The spec is a first draft: review it before planning." : "#{formed} The model was unavailable, so only the problem is filled in, from the requests."
+  end
+
+  def set_work_item
+    @work_item = ::FeatureMachine::WorkItem.find(params[:id])
+  end
+
+  def work_item_params
+    params.expect(work_item: [ :title, :kind, :status, :summary, :problem, :scope, :acceptance_criteria, :progress_note, :pull_request_url ])
+  end
+end

data/app/controllers/feature_machine/base_controller.rb

@@ -0,0 +1,10 @@
+# The engine's signed-in pages: your requests, your bug reports, the roadmap.
+# The parent is the host's (config.parent_controller, ApplicationController by
+# default), so its layout and auth filters run first; the engine then insists
+# on a user of its own from config.current_user.
+class FeatureMachine::BaseController < FeatureMachine.config.parent_controller.constantize
+  include FeatureMachine::CurrentUser
+  include FeatureMachine::EngineLayout
+
+  before_action :require_feature_machine_user
+end

data/app/controllers/feature_machine/bug_reports_controller.rb

@@ -0,0 +1,29 @@
+# Bug reports are requests of kind `bug`, taken in through their own door,
+# because a bug asks a different question than a feature does.
+class FeatureMachine::BugReportsController < FeatureMachine::BaseController
+  # "Your bug reports": only ever the signed-in user's own, since a report can
+  # describe their data.
+  def index
+    @bug_reports = ::FeatureMachine::Request.owned_by(feature_machine_user).bug.includes(:work_item).newest_first
+  end
+
+  def new
+    @bug_report = ::FeatureMachine::Request.bug.new
+  end
+
+  def create
+    @bug_report = ::FeatureMachine::Request.owned_by(feature_machine_user).bug.build(bug_report_params)
+
+    if @bug_report.save
+      redirect_to bug_reports_path, notice: "Thanks. Only you can see this report; its status will update here."
+    else
+      render :new, status: :unprocessable_entity
+    end
+  end
+
+  private
+
+  def bug_report_params
+    params.expect(bug_report: [ :title, :description ])
+  end
+end

data/app/controllers/feature_machine/feature_requests_controller.rb

@@ -0,0 +1,27 @@
+class FeatureMachine::FeatureRequestsController < FeatureMachine::BaseController
+  # "Your feature requests": only ever the signed-in user's own. What everyone
+  # can see is the roadmap, which lists work items rather than requests.
+  def index
+    @feature_requests = ::FeatureMachine::Request.owned_by(feature_machine_user).feature.includes(:work_item).newest_first
+  end
+
+  def new
+    @feature_request = ::FeatureMachine::Request.new
+  end
+
+  def create
+    @feature_request = ::FeatureMachine::Request.owned_by(feature_machine_user).feature.build(feature_request_params)
+
+    if @feature_request.save
+      redirect_to feature_requests_path, notice: "Thanks. Its status will update here."
+    else
+      render :new, status: :unprocessable_entity
+    end
+  end
+
+  private
+
+  def feature_request_params
+    params.expect(feature_request: [ :title, :description ])
+  end
+end

data/app/controllers/feature_machine/mcp_controller.rb

@@ -0,0 +1,36 @@
+# Stateless MCP endpoint (streamable HTTP, JSON responses). Each POST is an
+# independent JSON-RPC exchange. Users' agents file and follow their own
+# requests; a maintainer token also gets the three work-item tools the
+# fulfilment agent calls. Only bearer tokens count here: a browser session
+# cookie is never an MCP credential, so no page can drive these tools.
+class FeatureMachine::McpController < ActionController::API
+  def handle
+    result = server.handle_json(request.body.read)
+    result.nil? ? head(:accepted) : render(json: result)
+  end
+
+  # Stateless: no server-initiated stream to offer on GET.
+  def reject_get
+    head :method_not_allowed
+  end
+
+  private
+
+  def server
+    MCP::Server.new(
+      name: "feature_machine",
+      title: FeatureMachine.config.product_name,
+      version: FeatureMachine::VERSION,
+      instructions: "Feature requests, bug reports and the roadmap for #{FeatureMachine.config.product_name}.",
+      tools: FeatureMachine::Mcp.for(credential),
+      server_context: { credential: credential }
+    )
+  end
+
+  def credential
+    return @credential if defined?(@credential)
+
+    found = request.env[FeatureMachine::ENV_KEY]
+    @credential = (found unless found.respond_to?(:session?) && found.session?)
+  end
+end

data/app/controllers/feature_machine/roadmap_controller.rb

@@ -0,0 +1,9 @@
+# The roadmap and changelog: what is being built, what is queued, and what
+# shipped. It lists work items, not raw requests, so it reads as a product
+# changelog rather than a suggestion box. Signed-in users only; agents read
+# the same thing at GET /api/roadmap with a token.
+class FeatureMachine::RoadmapController < FeatureMachine::BaseController
+  def show
+    @roadmap = ::FeatureMachine::Roadmap.new
+  end
+end

data/app/helpers/feature_machine/feature_requests_helper.rb

@@ -0,0 +1,90 @@
+module FeatureMachine::FeatureRequestsHelper
+  # Status -> the design system's status tone. One place, so the board, the
+  # summary strip and any future email all agree on what "planned" looks like.
+  STATUS_TONES = {
+    "requested" => :neutral,
+    "planned" => :info,
+    "in_progress" => :progress,
+    "shipped" => :success,
+    "declined" => :danger
+  }.freeze
+
+  STATUS_LABELS = {
+    "requested" => "Requested",
+    "planned" => "Planned",
+    "in_progress" => "In progress",
+    "shipped" => "Shipped",
+    "declined" => "Declined"
+  }.freeze
+
+  # A bug isn't "requested" or "shipped"; same lifecycle, said the way the
+  # reporter would.
+  BUG_STATUS_LABELS = STATUS_LABELS.merge(
+    "requested" => "Reported",
+    "planned" => "Confirmed",
+    "in_progress" => "Being fixed",
+    "shipped" => "Fixed",
+    "declined" => "Won't fix"
+  ).freeze
+
+  # What each status means for the person who reported the bug.
+  BUG_STATUS_BLURBS = {
+    "requested" => "We have your report and haven't looked at it yet.",
+    "planned" => "Confirmed and queued for a fix.",
+    "in_progress" => "A fix is being worked on now.",
+    "shipped" => "The fix is live.",
+    "declined" => "We're not going to change this."
+  }.freeze
+
+  # What each status means for the person who asked for the feature. The
+  # shipped line names the host's product, so it is built at call time from
+  # FeatureMachine.config rather than frozen here.
+  STATUS_BLURBS = {
+    "requested" => "We have your request and haven't decided on it yet.",
+    "planned" => "Accepted and queued. It's on the roadmap.",
+    "in_progress" => "Being built right now.",
+    "shipped" => "Live on %{product}.",
+    "declined" => "We're not going to build this."
+  }.freeze
+
+  # The one-line explanation of where a request stands, worded by kind.
+  def request_status_blurb(feature_request)
+    blurbs = feature_request.bug? ? BUG_STATUS_BLURBS : STATUS_BLURBS
+    format(blurbs.fetch(feature_request.status), product: FeatureMachine.config.product_name)
+  end
+
+  # The status chip for a request: tone from the status, pulse while in
+  # progress, wording by kind.
+  def feature_request_status(feature_request)
+    status = feature_request.status
+    labels = feature_request.bug? ? BUG_STATUS_LABELS : STATUS_LABELS
+    feature_machine_status(tone: STATUS_TONES.fetch(status), pulse: feature_request.in_progress?) do
+      labels.fetch(status)
+    end
+  end
+
+  # Engine-local status chip. Emits the same class hooks the host's design
+  # system styles (cn-nr-status*), so the engine owns no CSS and no component
+  # dependency; a host without those hooks still gets a sane unstyled chip.
+  def feature_machine_status(tone: :neutral, pulse: false, &block)
+    classes = [
+      "cn-nr-status inline-flex items-center gap-1 whitespace-nowrap rounded-full px-2 py-0.5 text-xs font-semibold",
+      "cn-nr-status-tone-#{tone}"
+    ].join(" ")
+    data = { slot: "nr-status", tone: tone }
+    data[:pulse] = "true" if pulse
+    content_tag(:span, class: classes, data: data) do
+      safe_join([
+        content_tag(:span, "", class: "cn-nr-status-dot size-1.5 shrink-0 rounded-full bg-current",
+                                data: { slot: "nr-status-dot" }, aria: { hidden: true }),
+        capture(&block)
+      ], " ")
+    end
+  end
+
+  # A host link the engine offers only when the host configured it.
+  def feature_machine_host_link(name, text, **options)
+    path = FeatureMachine.config.host_path(name, self)
+    link_to(text, path, **options) if path
+  end
+end

data/app/helpers/feature_machine/work_items_helper.rb

@@ -0,0 +1,99 @@
+module FeatureMachine::WorkItemsHelper
+  WORK_ITEM_STATUS_TONES = {
+    "draft" => :neutral,
+    "planned" => :info,
+    "in_progress" => :progress,
+    "in_review" => :info,
+    "shipped" => :success,
+    "declined" => :danger
+  }.freeze
+
+  WORK_ITEM_STATUS_LABELS = {
+    "draft" => "Draft",
+    "planned" => "Planned",
+    "in_progress" => "In progress",
+    "in_review" => "In review",
+    "shipped" => "Shipped",
+    "declined" => "Declined"
+  }.freeze
+
+  WORK_ITEM_STATUS_BLURBS = {
+    "draft" => "Formed from requests, not yet a commitment. Private until planned.",
+    "in_review" => "Built, with a pull request waiting on you. Users still see these as in progress.",
+    "in_progress" => "Being built right now.",
+    "planned" => "Accepted and queued. Order here isn't a promise about order of delivery.",
+    "shipped" => "Live on %{product}.",
+    "declined" => "Not going to happen."
+  }.freeze
+
+  def work_item_status_label(status)
+    WORK_ITEM_STATUS_LABELS.fetch(status.to_s)
+  end
+
+  # The shipped line names the host's product, so it is built at call time
+  # from FeatureMachine.config rather than frozen here.
+  def work_item_status_blurb(status)
+    format(WORK_ITEM_STATUS_BLURBS.fetch(status.to_s), product: FeatureMachine.config.product_name)
+  end
+
+  # The status chip. Admin pages show the real status; anything users see
+  # passes `public: true`, which folds review into "In progress".
+  def work_item_status(work_item, public: false)
+    status = public ? work_item.public_status : work_item.status
+    work_item_status_chip(tone: WORK_ITEM_STATUS_TONES.fetch(status), pulse: status == "in_progress") do
+      work_item_status_label(status)
+    end
+  end
+
+  # Engine-local status chip. Emits the same class hooks the host's design
+  # system styles (cn-nr-status*), so the engine owns no CSS and no component
+  # dependency; a host without those hooks still gets a sane unstyled chip.
+  def work_item_status_chip(tone: :neutral, pulse: false, &block)
+    classes = [
+      "cn-nr-status inline-flex items-center gap-1 whitespace-nowrap rounded-full px-2 py-0.5 text-xs font-semibold",
+      "cn-nr-status-tone-#{tone}"
+    ].join(" ")
+    data = { slot: "nr-status", tone: tone }
+    data[:pulse] = "true" if pulse
+    content_tag(:span, class: classes, data: data) do
+      safe_join([
+        content_tag(:span, "", class: "cn-nr-status-dot size-1.5 shrink-0 rounded-full bg-current",
+                                data: { slot: "nr-status-dot" }, aria: { hidden: true }),
+        capture(&block)
+      ], " ")
+    end
+  end
+
+  # "Feature" / "Bug", or "Fix" once a bug has shipped: the changelog reads
+  # as what changed, not what was wrong.
+  def work_kind_label(record)
+    return "Fix" if record.bug? && record.try(:shipped?)
+
+    record.bug? ? "Bug" : "Feature"
+  end
+
+  # How much demand sits behind a work item, counting people rather than requests.
+  def work_item_demand(work_item)
+    people = work_item.feature_requests.map(&:user_id).uniq.size
+    people.zero? ? nil : "#{pluralize(people, 'person')} asked"
+  end
+
+  # The pull request's address, rebuilt from the fixed GitHub origin and the
+  # validated path. Nil when there is no usable pull request.
+  def pull_request_href(work_item)
+    path = work_item.pull_request_path
+    "#{::FeatureMachine::WorkItem::GITHUB}#{path}" if path
+  end
+
+  # A new item may start anywhere; a saved one offers where it stands plus
+  # the moves its transition table allows.
+  def work_item_status_options(work_item = nil)
+    statuses = ::FeatureMachine::WorkItem.statuses.keys
+    statuses &= [ work_item.status_in_database, *work_item.next_statuses ] if work_item&.persisted?
+    statuses.map { |status| [ work_item_status_label(status), status ] }
+  end
+
+  def work_item_relation_options
+    ::FeatureMachine::WorkItemRelation::KINDS.map { |kind, (forward, _inverse)| [ forward, kind ] }
+  end
+end

data/app/jobs/feature_machine/application_job.rb

@@ -0,0 +1,6 @@
+module FeatureMachine
+  # The engine's own job base, so a host needs no ApplicationJob of its own.
+  # Queue adapter and the like still come from the host's Active Job config.
+  class ApplicationJob < ActiveJob::Base
+  end
+end

data/app/jobs/feature_machine/request_embedding_job.rb

@@ -0,0 +1,12 @@
+module FeatureMachine
+  class RequestEmbeddingJob < ApplicationJob
+    queue_as :default
+
+    def perform(feature_request_id)
+      feature_request = ::FeatureMachine::Request.find_by(id: feature_request_id)
+      return unless feature_request
+
+      RequestEmbeddingService.new(feature_request).call
+    end
+  end
+end

data/app/jobs/feature_machine/work_item_embedding_job.rb

@@ -0,0 +1,12 @@
+module FeatureMachine
+  class WorkItemEmbeddingJob < ApplicationJob
+    queue_as :default
+
+    def perform(work_item_id)
+      work_item = ::FeatureMachine::WorkItem.find_by(id: work_item_id)
+      return unless work_item
+
+      WorkItemEmbeddingService.new(work_item).call
+    end
+  end
+end

data/app/models/feature_machine/request.rb

@@ -0,0 +1,111 @@
+# Something a user asked the host app for: a feature, or a bug report. This
+# is the raw intake record, in the requester's own words. What actually gets
+# built is a WorkItem; triage is the act of bucketing requests into one.
+#
+# A request is visible to the person who filed it and to admins, never to
+# other users. What everyone signed in can see is the roadmap of work items.
+#
+# Requesters can only create. A request's status follows its work item; the
+# only status an admin sets directly is `declined`.
+module FeatureMachine
+  class Request < ApplicationRecord
+    self.table_name = "feature_requests"
+
+    # Phase 2 keeps the public surface unchanged: params keys, dom_id,
+    # polymorphic route helpers and i18n keys all still read `feature_request`.
+    # Requests filed before embeddings were switched on never got one, and
+    # triage leaves them out of every group. Embeds each one now, in this
+    # process: queued jobs would die with a rake task on an in-process
+    # adapter. Returns how many it filled; the rest stay nil, as a failed
+    # call leaves them.
+    def self.backfill_embeddings
+      return 0 unless ::FeatureMachine.config.embeddings?
+
+      ids = unembedded.ids
+      ids.each { |id| RequestEmbeddingJob.perform_now(id) }
+      ids.size - unembedded.where(id: ids).count
+    end
+
+    def self.model_name
+      @_model_name ||= ActiveModel::Name.new(self, nil, "FeatureRequest")
+    end
+
+    belongs_to :user, class_name: ::FeatureMachine.config.user_class
+    belongs_to :work_item, class_name: "FeatureMachine::WorkItem", optional: true
+
+    enum :kind, { feature: 0, bug: 1 }, validate: true
+    enum :status, { requested: 0, planned: 1, in_progress: 2, shipped: 3, declined: 4 }, validate: true
+
+    # The only statuses set on a request directly, and only while it has no
+    # work item: decline it, or reopen it. Every other status is copied from
+    # the work item it joins (follow_work_item, or WorkItem#sync_requests).
+    DIRECT_STATUSES = %w[requested declined].freeze
+
+    has_neighbors :embedding
+
+    validates :title, presence: true, length: { minimum: 8, maximum: 120 }
+    validates :description, length: { maximum: 2000 }
+    validates :progress_note, length: { maximum: 1000 }
+    validate :status_set_directly_only_while_unattached, on: :update
+
+    scope :newest_first, -> { order(created_at: :desc) }
+    scope :oldest_first, -> { order(created_at: :asc) }
+    scope :embedded,     -> { where.not(embedding: nil) }
+    scope :unembedded,   -> { where(embedding: nil) }
+    # One requester's own requests. The engine never asks the host's user
+    # model for an association, so a host needs no has_many to adopt it.
+    scope :owned_by,     ->(user) { where(user: user) }
+    # Still waiting for an admin: not bucketed into a work item, not declined.
+    scope :untriaged,    -> { requested.where(work_item_id: nil) }
+
+    before_save :follow_work_item, if: :will_save_change_to_work_item_id?
+    before_save :stamp_shipped_at
+    after_commit :enqueue_embedding, on: [ :create, :update ], if: :embedding_wanted?
+    # Hosts hear about status moves (planned, shipped, declined...) to tell the
+    # requester wherever they asked; the engine itself only shows the roadmap.
+    after_update_commit :announce_status_change, if: -> { saved_change_to_status? && ::FeatureMachine.config.on_status_change }
+
+    private
+
+    # Joining or leaving a work item rewrites status in before_save, so a
+    # status passed alongside a work_item_id change is moot. Without one, a
+    # direct move is only requested <-> declined, and only when unattached.
+    def status_set_directly_only_while_unattached
+      return unless will_save_change_to_status?
+      return if will_save_change_to_work_item_id?
+      return if work_item.nil? && DIRECT_STATUSES.include?(status)
+
+      errors.add(:status, work_item ? "follows its work item" : "can only be set to requested or declined")
+    end
+
+    # Joining a work item means taking on its public state; leaving one puts
+    # the request back in the triage inbox.
+    def follow_work_item
+      if work_item
+        assign_attributes(work_item.request_attributes)
+      else
+        assign_attributes(status: :requested, progress_note: nil, shipped_at: nil)
+      end
+    end
+
+    def stamp_shipped_at
+      self.shipped_at ||= Time.current if shipped? && (new_record? || will_save_change_to_status?)
+    end
+
+    def embedding_wanted?
+      ::FeatureMachine.config.embeddings? && embedding_stale?
+    end
+
+    def embedding_stale?
+      saved_change_to_title? || saved_change_to_description? || embedding.nil?
+    end
+
+    def announce_status_change
+      ::FeatureMachine.config.on_status_change.call(self)
+    end
+
+    def enqueue_embedding
+      RequestEmbeddingJob.perform_later(id)
+    end
+  end
+end

data/app/models/feature_machine/roadmap.rb

@@ -0,0 +1,24 @@
+module FeatureMachine
+  # The roadmap as shown to users and their agents: upcoming work items by
+  # status, then shipped ones as a changelog by month. It is read straight from
+  # work items, so it is current the moment a status changes.
+  class Roadmap
+    # @return [Hash{String => Array<WorkItem>}] in_progress then planned, empty sections included
+    def upcoming
+      @upcoming ||= begin
+        grouped = WorkItem.upcoming.includes(:feature_requests).newest_first.group_by(&:public_status)
+        WorkItem::UPCOMING.index_with { |status| grouped.fetch(status, []) }
+      end
+    end
+
+    # @return [Hash{Date => Array<WorkItem>}] first day of each month => items shipped in it, newest first
+    def changelog
+      @changelog ||= WorkItem.changelog.includes(:feature_requests)
+        .group_by { |item| item.shipped_at.beginning_of_month.to_date }
+    end
+
+    def empty?
+      upcoming.values.all?(&:empty?) && changelog.empty?
+    end
+  end
+end