feature_machine 0.1.0

data/app/views/feature_machine/feature_requests/index.html.erb

@@ -0,0 +1,44 @@
+<% product = FeatureMachine.config.product_name %>
+<% roadmap = FeatureMachine.config.host_path(:roadmap_path, self) %>
+<% bug_reports = FeatureMachine.config.host_path(:bug_reports_path, self) %>
+<% button = "cn-button inline-flex shrink-0 items-center justify-center whitespace-nowrap transition-all outline-none disabled:pointer-events-none disabled:opacity-50 [&_svg]:pointer-events-none [&_svg]:shrink-0 group/button select-none cn-button-size-default" %>
+<% content_for :title, "Your feature requests — #{product}" %>
+<% content_for :head do %>
+  <meta name="robots" content="noindex">
+<% end %>
+
+<div class="cn-container">
+  <%= render "feature_machine/flash" %>
+  <header class="cn-page-header">
+    <p class="cn-page-header-eyebrow">Roadmap</p>
+    <h1 class="cn-page-header-title">Your feature requests</h1>
+    <p class="cn-page-header-lede">
+      What you've asked for and where each request stands. Only you can see
+      this page.<% if roadmap %> What requests turn into is on the <%= link_to "roadmap", roadmap %>.<% end %>
+    </p>
+    <div class="mt-5 flex flex-wrap items-center gap-3">
+      <a href="<%= new_feature_request_path %>" data-slot="button" data-variant="default" data-size="default"
+         class="<%= button %> cn-button-variant-default"><span data-slot="label" class="contents">Request a feature</span></a>
+      <% if bug_reports %>
+        <a href="<%= bug_reports %>" data-slot="button" data-variant="ghost" data-size="default"
+           class="<%= button %> cn-button-variant-ghost"><span data-slot="label" class="contents">Your bug reports</span></a>
+      <% end %>
+    </div>
+  </header>
+
+  <% if @feature_requests.empty? %>
+    <div data-slot="empty" class="cn-empty flex w-full min-w-0 flex-1 flex-col items-center justify-center text-center text-balance">
+      <div data-slot="empty-header" class="cn-empty-header flex max-w-sm flex-col items-center">
+        <div data-slot="empty-icon" data-variant="icon" class="cn-empty-media flex shrink-0 items-center justify-center [&_svg]:pointer-events-none [&_svg]:shrink-0 cn-empty-media-icon">
+          <svg xmlns="http://www.w3.org/2000/svg" class="size-6" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M15 14c.2-1 .7-1.7 1.5-2.5 1-.9 1.5-2.2 1.5-3.5A6 6 0 0 0 6 8c0 1 .2 2.2 1.5 3.5.7.7 1.3 1.5 1.5 2.5"/><path d="M9 18h6"/><path d="M10 22h4"/></svg>
+        </div>
+        <h2 data-slot="empty-title" class="cn-empty-title cn-font-heading">No feature requests yet</h2>
+        <p data-slot="empty-description" class="cn-empty-description text-muted-foreground [&>a]:underline [&>a]:underline-offset-4 [&>a:hover]:text-primary">What would make <%= product %> more useful to you? Ask, and follow it here.</p>
+      </div>
+    </div>
+  <% else %>
+    <div class="cn-entry-list" id="feature-requests">
+      <%= render partial: "feature_machine/feature_requests/feature_request", collection: @feature_requests %>
+    </div>
+  <% end %>
+</div>

data/app/views/feature_machine/feature_requests/new.html.erb

@@ -0,0 +1,84 @@
+<% product = FeatureMachine.config.product_name %>
+<% new_bug_report = FeatureMachine.config.host_path(:new_bug_report_path, self) %>
+<% errors = @feature_request.errors %>
+<% button = "cn-button inline-flex shrink-0 items-center justify-center whitespace-nowrap transition-all outline-none disabled:pointer-events-none disabled:opacity-50 [&_svg]:pointer-events-none [&_svg]:shrink-0 group/button select-none cn-button-size-default" %>
+<% field_class = "cn-field grid group/field w-full" %>
+<% label_class = "cn-label flex items-center select-none cn-field-label group/field-label peer/field-label flex w-fit items-center" %>
+<% hint_class = "cn-field-description [&>a:hover]:text-primary [&>a]:underline [&>a]:underline-offset-4 font-normal leading-normal" %>
+<% content_for :title, "Request a feature — #{product}" %>
+<% content_for :head do %>
+  <meta name="robots" content="noindex">
+<% end %>
+
+<div class="cn-container">
+  <%= render "feature_machine/flash" %>
+  <header class="cn-page-header">
+    <p class="cn-page-header-eyebrow">Roadmap</p>
+    <h1 class="cn-page-header-title">Request a feature</h1>
+    <p class="cn-page-header-lede">
+      Tell us what you're trying to do. Only you and the maintainers see what
+      you write; you can follow it under
+      <%= link_to "your feature requests", feature_requests_path %>.
+      <% if new_bug_report %><%= link_to "Reporting a bug instead?", new_bug_report %><% end %>
+    </p>
+  </header>
+
+  <%# Plain form_with: the same Field / Input / Textarea / Button markup the
+      host's Poetry builder renders, written out so the engine carries no
+      dependency on the host's UI kit. Field order inside each cn-field:
+      label, control, hint, error. aria-required rides the label-station
+      rule (never the native attribute); aria-describedby points at the
+      hint and, on a bounce, the error. %>
+  <%= form_with(model: @feature_request, class: "flex max-w-xl flex-col gap-5") do |form| %>
+    <% if errors.any? %>
+      <div data-slot="alert" data-variant="destructive" role="alert" class="cn-alert relative w-full group/alert cn-alert-variant-destructive">
+        <div data-slot="alert-title" class="cn-alert-title [&_a]:hover:text-foreground [&_a]:underline [&_a]:underline-offset-3">That didn't go through</div>
+        <div data-slot="alert-description" class="cn-alert-description [&_a]:hover:text-foreground [&_a]:underline [&_a]:underline-offset-3">
+          <ul class="list-inside list-disc">
+            <% errors.full_messages.each do |message| %>
+              <li><%= message %></li>
+            <% end %>
+          </ul>
+        </div>
+      </div>
+    <% end %>
+
+    <% title_errors = errors[:title] %>
+    <div data-slot="field" data-invalid="<%= title_errors.any? %>" class="<%= field_class %>">
+      <%= form.label :title, class: label_class, data: { slot: "field-label" } %>
+      <%= form.text_field :title,
+            class: "cn-input w-full min-w-0 outline-none",
+            placeholder: "e.g. Let me export my data as a CSV file",
+            maxlength: 120, minlength: 8, autofocus: true,
+            "aria-required": true,
+            "aria-invalid": (true if title_errors.any?),
+            "aria-describedby": ["feature_request_title_hint", ("feature_request_title_error" if title_errors.any?)].compact.join(" ") %>
+      <p id="feature_request_title_hint" data-slot="field-description" class="<%= hint_class %>">One line, the way you'd say it to a friend.</p>
+      <% if title_errors.any? %>
+        <p id="feature_request_title_error" data-slot="field-error" class="cn-field-error font-normal"><%= title_errors.to_sentence %></p>
+      <% end %>
+    </div>
+
+    <% description_errors = errors[:description] %>
+    <div data-slot="field" data-invalid="<%= description_errors.any? %>" class="<%= field_class %>">
+      <%= form.label :description, class: label_class, data: { slot: "field-label" } %>
+      <%= form.text_area :description,
+            class: "cn-textarea flex field-sizing-content min-h-16 w-full outline-none",
+            rows: 6, maxlength: 2000,
+            placeholder: "What are you trying to do, and what gets in the way today?",
+            "aria-invalid": (true if description_errors.any?),
+            "aria-describedby": ["feature_request_description_hint", ("feature_request_description_error" if description_errors.any?)].compact.join(" ") %>
+      <p id="feature_request_description_hint" data-slot="field-description" class="<%= hint_class %>">The problem, not the implementation. We'll figure out the how.</p>
+      <% if description_errors.any? %>
+        <p id="feature_request_description_error" data-slot="field-error" class="cn-field-error font-normal"><%= description_errors.to_sentence %></p>
+      <% end %>
+    </div>
+
+    <div class="flex items-center gap-3">
+      <button type="submit" name="commit" value="Request it" data-slot="button" data-variant="default" data-size="default"
+              class="<%= button %> cn-button-variant-default"><span data-slot="label" class="contents">Request it</span></button>
+      <a href="<%= feature_requests_path %>" data-slot="button" data-variant="ghost" data-size="default"
+         class="<%= button %> cn-button-variant-ghost"><span data-slot="label" class="contents">Back to your requests</span></a>
+    </div>
+  <% end %>
+</div>

data/app/views/feature_machine/roadmap/_work_item.html.erb

@@ -0,0 +1,34 @@
+<%# One roadmap entry: the public face of a work item. No spec; that is the
+    maintainer's working document. %>
+<article id="<%= dom_id(work_item) %>" data-slot="nr-entry" data-state="ready"
+         class="cn-nr-entry flex gap-4 py-5 border-b border-border group/entry cn-nr-entry-state-ready">
+  <div data-slot="nr-entry-body" class="cn-nr-entry-body order-1 min-w-0 flex-1">
+    <div class="cn-nr-entry-title-row flex flex-wrap items-baseline gap-3">
+      <h3 data-slot="nr-entry-title" class="cn-nr-entry-title"><%= work_item.title %></h3>
+      <span class="cn-nr-entry-status"><%= work_item_status(work_item, public: true) %></span>
+    </div>
+
+    <div data-slot="nr-entry-meta" class="cn-nr-entry-meta mt-2 flex flex-wrap items-baseline gap-x-2 gap-y-1 text-sm">
+      <span class="cn-nr-entry-meta-item"><%= work_kind_label(work_item) %></span>
+      <% if work_item.shipped_at.present? %>
+        <span class="cn-nr-entry-meta-sep" aria-hidden="true">&middot;</span>
+        <span class="cn-nr-entry-meta-item">shipped <%= work_item.shipped_at.strftime("%b %-d, %Y") %></span>
+      <% end %>
+      <% if (demand = work_item_demand(work_item)) %>
+        <span class="cn-nr-entry-meta-sep" aria-hidden="true">&middot;</span>
+        <span class="cn-nr-entry-meta-item"><%= demand %></span>
+      <% end %>
+    </div>
+
+    <p data-slot="nr-entry-summary" class="cn-nr-entry-summary mt-2"><%= work_item.summary %></p>
+
+    <% if work_item.progress_note.present? %>
+      <div data-slot="nr-entry-details" class="cn-nr-entry-details mt-4 pt-4">
+        <div class="cn-entry-section">
+          <h4 class="cn-entry-section-title">Progress</h4>
+          <p class="cn-entry-section-content"><%= simple_format(work_item.progress_note, {}, wrapper_tag: "span") %></p>
+        </div>
+      </div>
+    <% end %>
+  </div>
+</article>

data/app/views/feature_machine/roadmap/show.html.erb

@@ -0,0 +1,70 @@
+<% product = FeatureMachine.config.product_name %>
+<% button = "cn-button inline-flex shrink-0 items-center justify-center whitespace-nowrap transition-all outline-none disabled:pointer-events-none disabled:opacity-50 [&_svg]:pointer-events-none [&_svg]:shrink-0 group/button select-none cn-button-size-default" %>
+<% new_bug_report = FeatureMachine.config.host_path(:new_bug_report_path, self) %>
+<% bug_reports = FeatureMachine.config.host_path(:bug_reports_path, self) %>
+<% content_for :title, "Roadmap — #{product}" %>
+<% content_for :head do %>
+  <meta name="robots" content="noindex">
+<% end %>
+
+<div class="cn-container">
+  <%= render "feature_machine/flash" %>
+  <header class="cn-page-header">
+    <p class="cn-page-header-eyebrow">Roadmap</p>
+    <h1 class="cn-page-header-title">What's being built, and what shipped</h1>
+    <p class="cn-page-header-lede">
+      Each entry is a piece of work shaped from what people asked for. Planned
+      work first, then the changelog.
+    </p>
+    <div class="mt-5 flex flex-wrap items-center gap-3">
+      <a href="<%= new_feature_request_path %>" data-slot="button" data-variant="default" data-size="default"
+         class="<%= button %> cn-button-variant-default"><span data-slot="label" class="contents">Request a feature</span></a>
+      <% if new_bug_report %>
+        <a href="<%= new_bug_report %>" data-slot="button" data-variant="outline" data-size="default"
+           class="<%= button %> cn-button-variant-outline"><span data-slot="label" class="contents">Report a bug</span></a>
+      <% end %>
+      <a href="<%= feature_requests_path %>" data-slot="button" data-variant="ghost" data-size="default"
+         class="<%= button %> cn-button-variant-ghost"><span data-slot="label" class="contents">Your requests</span></a>
+      <% if bug_reports %>
+        <a href="<%= bug_reports %>" data-slot="button" data-variant="ghost" data-size="default"
+           class="<%= button %> cn-button-variant-ghost"><span data-slot="label" class="contents">Your bug reports</span></a>
+      <% end %>
+    </div>
+  </header>
+
+  <% if @roadmap.empty? %>
+    <div data-slot="empty" class="cn-empty flex w-full min-w-0 flex-1 flex-col items-center justify-center text-center text-balance">
+      <div data-slot="empty-header" class="cn-empty-header flex max-w-sm flex-col items-center">
+        <h2 data-slot="empty-title" class="cn-empty-title cn-font-heading">Nothing on the roadmap yet</h2>
+        <p data-slot="empty-description" class="cn-empty-description text-muted-foreground">Requests are still being triaged. Planned work will appear here.</p>
+      </div>
+    </div>
+  <% end %>
+
+  <% @roadmap.upcoming.each do |status, work_items| %>
+    <% next if work_items.empty? %>
+    <section class="mt-12" aria-labelledby="roadmap-<%= status %>">
+      <h2 id="roadmap-<%= status %>" class="flex items-baseline gap-3">
+        <%= work_item_status(work_items.first, public: true) %>
+        <span class="text-sm text-muted-foreground"><%= pluralize(work_items.size, "item") %></span>
+      </h2>
+      <p class="cn-page-header-lede mt-2"><%= work_item_status_blurb(status) %></p>
+      <div class="cn-entry-list">
+        <%= render partial: "feature_machine/roadmap/work_item", collection: work_items %>
+      </div>
+    </section>
+  <% end %>
+
+  <% if @roadmap.changelog.any? %>
+    <section class="mt-12" aria-labelledby="changelog">
+      <h2 id="changelog" class="cn-page-header-title">Changelog</h2>
+      <p class="cn-page-header-lede mt-2">Features shipped and bugs fixed, newest first.</p>
+      <% @roadmap.changelog.each do |month, work_items| %>
+        <h3 class="changelog-month" id="changelog-<%= month.strftime("%Y-%m") %>"><%= month.strftime("%B %Y") %></h3>
+        <div class="cn-entry-list">
+          <%= render partial: "feature_machine/roadmap/work_item", collection: work_items %>
+        </div>
+      <% end %>
+    </section>
+  <% end %>
+</div>

data/app/views/layouts/feature_machine.html.erb

@@ -0,0 +1,21 @@
+<%# The engine's standalone shell, used only when a host sets
+    FeatureMachine.config.layout = "feature_machine". No host assets are
+    assumed: hosts add their own via content_for :head or name their own layout. %>
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width,initial-scale=1">
+    <title><%= content_for?(:title) ? content_for(:title) : FeatureMachine.config.product_name %></title>
+    <%= csrf_meta_tags %>
+    <%= csp_meta_tag %>
+    <%= yield :head %>
+  </head>
+  <body>
+    <% if notice.present? %><p role="status" data-slot="flash-notice"><%= notice %></p><% end %>
+    <% if alert.present? %><p role="alert" data-slot="flash-alert"><%= alert %></p><% end %>
+    <main>
+      <%= yield %>
+    </main>
+  </body>
+</html>

data/db/migrate/20260910180000_create_feature_requests.rb

@@ -0,0 +1,18 @@
+class CreateFeatureRequests < ActiveRecord::Migration[8.1]
+  def change
+    create_table :feature_requests do |t|
+      t.references :user, null: false, foreign_key: true
+      t.string :title, null: false
+      t.text :description
+      # requested 0, planned 1, in_progress 2, shipped 3, declined 4 (FeatureRequest#status)
+      t.integer :status, null: false, default: 0
+      # Public progress note the maintainer writes when the status moves.
+      t.text :progress_note
+      t.datetime :shipped_at
+
+      t.timestamps
+    end
+
+    add_index :feature_requests, [ :status, :created_at ]
+  end
+end

data/db/migrate/20261004120000_create_work_items.rb

@@ -0,0 +1,52 @@
+# Splits "what a user asked for" (feature_requests, now also bug reports) from
+# "what we will build" (work_items). Requests are bucketed into work items by
+# an admin during triage; work items relate to one another as a graph.
+class CreateWorkItems < ActiveRecord::Migration[8.1]
+  def change
+    # The embedding columns below need pgvector; a fresh host may not have it yet.
+    enable_extension "vector"
+
+    create_table :work_items do |t|
+      t.string :title, null: false
+      # feature 0, bug 1 (WorkItem#kind)
+      t.integer :kind, null: false, default: 0
+      # draft 0, planned 1, in_progress 2, shipped 3, declined 4 (WorkItem#status)
+      t.integer :status, null: false, default: 0
+      # The hand-off spec.
+      t.text :problem
+      t.text :scope
+      t.text :acceptance_criteria
+      # Public: the one-paragraph roadmap/changelog entry and the progress note.
+      t.text :summary
+      t.text :progress_note
+      t.datetime :shipped_at
+      t.vector :embedding, limit: 1536
+      t.datetime :embedded_at
+      t.string :embedding_input_digest
+
+      t.timestamps
+    end
+    add_index :work_items, [ :status, :shipped_at ]
+
+    create_table :work_item_relations do |t|
+      t.references :from_work_item, null: false, foreign_key: { to_table: :work_items }
+      t.references :to_work_item, null: false, foreign_key: { to_table: :work_items }
+      t.string :kind, null: false, default: "related"
+
+      t.timestamps
+    end
+    add_index :work_item_relations, [ :from_work_item_id, :to_work_item_id, :kind ],
+              unique: true, name: "index_work_item_relations_uniqueness"
+
+    change_table :feature_requests do |t|
+      # feature 0, bug 1 (FeatureRequest#kind)
+      t.integer :kind, null: false, default: 0
+      t.references :work_item, foreign_key: true
+      t.datetime :embedded_at
+      t.string :embedding_input_digest
+    end
+    add_column :feature_requests, :embedding, :vector, limit: 1536
+
+    add_column :users, :admin, :boolean, null: false, default: false
+  end
+end

data/db/migrate/20261006120000_add_pull_request_url_to_work_items.rb

@@ -0,0 +1,7 @@
+# The pull request that implements a work item, attached by the agent that
+# opened it when it hands the work back for review.
+class AddPullRequestUrlToWorkItems < ActiveRecord::Migration[8.1]
+  def change
+    add_column :work_items, :pull_request_url, :string
+  end
+end

data/lib/feature_machine/auth.rb

@@ -0,0 +1,89 @@
+module FeatureMachine
+  module Auth
+    # Does this credential allow `scope`, by the engine's rules? The credential
+    # answers for itself, and for `maintainer` the host's admin predicate must
+    # agree. This is the one place the rule lives; controllers and tools call
+    # it rather than `credential.allows?` directly.
+    def self.allows?(credential, scope)
+      return false unless credential&.allows?(scope.to_s)
+      return true unless scope.to_s == MAINTAINER
+
+      FeatureMachine.config.admin?(credential.user)
+    end
+
+    # The "Authorization: Bearer <token>" value of a Rack env, or nil.
+    def self.bearer_token(env)
+      header = env["HTTP_AUTHORIZATION"].to_s
+      scheme, token = header.split(" ", 2)
+      token&.strip.presence if scheme&.casecmp?("bearer")
+    end
+
+    # The credential a signed-in browser session carries. `user` is resolved
+    # on first use, so installing the middleware costs nothing on requests
+    # that never ask. A session user may read and write their own requests;
+    # maintainer access needs the host's admin predicate.
+    class SessionCredential
+      def initialize(request, config: FeatureMachine.config)
+        @request = request
+        @config  = config
+      end
+
+      def user
+        return @user if defined?(@user)
+
+        @user = @config.user_for(@request)
+      end
+
+      def allows?(scope)
+        return false unless user
+
+        case scope.to_s
+        when READ, WRITE then true
+        when MAINTAINER  then @config.admin?(user)
+        else false
+        end
+      end
+
+      def session?
+        true
+      end
+    end
+
+    # Resolves a bearer token through `config.authenticate_api` and sets the
+    # env key when it finds a credential. A missing or bad token sets nothing,
+    # so the next middleware may still find one. Install before Session.
+    class Bearer
+      def initialize(app, resolver: nil)
+        @app      = app
+        @resolver = resolver
+      end
+
+      def call(env)
+        if env[ENV_KEY].nil? && (resolver = @resolver || FeatureMachine.config.authenticate_api)
+          token = Auth.bearer_token(env)
+          credential = resolver.call(token) if token
+          env[ENV_KEY] = credential if credential
+        end
+
+        @app.call(env)
+      end
+    end
+
+    # Sets a SessionCredential when nothing earlier in the stack set a
+    # credential and `config.session_auth` is on. Install last, after the
+    # host's session middleware.
+    class Session
+      def initialize(app)
+        @app = app
+      end
+
+      def call(env)
+        if env[ENV_KEY].nil? && FeatureMachine.config.session_auth
+          env[ENV_KEY] = SessionCredential.new(ActionDispatch::Request.new(env))
+        end
+
+        @app.call(env)
+      end
+    end
+  end
+end

data/lib/feature_machine/calibration/judge_cases.yml

@@ -0,0 +1,137 @@
+# Mutation calibration cases for FeatureMachine::Judge.
+#
+# Each case is one base request plus two mutants:
+#   equivalent: the same request in different words. The answer must not move.
+#   faulty:     one fact flipped. The answer must move to `faulty.expect`.
+#
+# A judge that moves on paraphrase is reading surface wording; a judge that
+# holds still on a flipped fact isn't reading at all. Requests are drawn from
+# the acceptance personas (lib/acceptance_personas.rb) and `open_items` mirrors
+# the active work items the maintainer persona seeds, so `duplicate_of_open_item`
+# has the same context it gets in triage.
+#
+# Expectations: probability questions use "high" (>= 0.5) or "low" (< 0.5);
+# score questions use one of the judge's labels. `thresholds` bound how far an
+# equivalent mutant may drift from the base before it counts as moved.
+#
+# Run against a live model with `rake feature_machine:calibrate_judge` (opt-in,
+# never in CI). judge_cases_test.rb only checks this file's shape.
+
+thresholds:
+  probability_drift: 0.3
+  score_drift: 0
+
+open_items:
+  - "[feature] Pin articles to the top of a public list"
+  - "[feature] Pending connection suggestions over MCP"
+  - "[feature] Webhooks for digest events"
+  - "[feature] Mark an article to reread later"
+
+cases:
+  - id: bug-stuck-drafts
+    question: bug
+    persona: drafter
+    base:
+      kind: bug
+      title: My drafts never finish fetching details
+      description: Three links have said 'Fetching details' since yesterday.
+      expect: high
+    equivalent:
+      kind: bug
+      title: Saved links stuck on 'Fetching details'
+      description: Since yesterday, three of my saved links are still showing 'Fetching details' and never fill in.
+    faulty:
+      kind: bug
+      title: Show progress while drafts fetch details
+      description: Fetching details takes a few seconds on my links. A progress bar would tell me it's working.
+      expect: low
+
+  - id: bug-csv-export
+    question: bug
+    persona: newcomer
+    base:
+      kind: feature
+      title: Export my library as CSV
+      description: I'd like to download everything I've saved as a CSV so I can keep a copy in a spreadsheet.
+      expect: low
+    equivalent:
+      kind: feature
+      title: Download my saved articles as a spreadsheet
+      description: Could there be a CSV download of my whole library? I want a backup I can open in a spreadsheet.
+    faulty:
+      kind: feature
+      title: Export my library as CSV
+      description: I downloaded everything I've saved as a CSV, but the file is empty apart from the header row.
+      expect: high
+
+  - id: duplicate-pinning
+    question: duplicate_of_open_item
+    persona: curator
+    base:
+      kind: feature
+      title: Keep my favourite articles at the top of my public page
+      description: I want two or three pieces to stay first on my public list instead of sliding down as I save new ones.
+      expect: high
+    equivalent:
+      kind: feature
+      title: Let me pin a few articles on my public list
+      description: New saves push my best pieces off the top of my public page. I'd like to fix a handful in place above everything else.
+    faulty:
+      kind: feature
+      title: Hide some articles from my public page
+      description: I want two or three pieces to stay off my public list while still being in my library.
+      expect: low
+
+  - id: duplicate-mcp-tagging
+    question: duplicate_of_open_item
+    persona: agentic
+    base:
+      kind: feature
+      title: Let agents tag articles over MCP
+      description: My agent can save and reflect on articles but has no way to add or remove tags on them.
+      expect: low
+    equivalent:
+      kind: feature
+      title: MCP tool for article tags
+      description: Agents can add articles and reflections through MCP, but there's no tool to set an article's tags.
+    faulty:
+      kind: feature
+      title: Let agents see suggested connections over MCP
+      description: My agent can create connections but has no way to list the ones the app has already suggested.
+      expect: high
+
+  - id: clarity-reading-time
+    question: clarity
+    persona: reader
+    base:
+      kind: feature
+      title: Show reading time on my public list
+      description: My newsletter subscribers click through from my public list and ask how long each piece is. A minutes estimate next to each article would let them pick what fits their time.
+      expect: High
+    equivalent:
+      kind: feature
+      title: Reading-time estimates on public list articles
+      description: People who subscribe to my newsletter browse my public list and want to know how long an article takes before opening it. Please show an estimated read time beside each one.
+    faulty:
+      kind: feature
+      title: Make my public list better
+      description: My newsletter subscribers use my public list. It could be better for them.
+      expect: Low
+
+  - id: clarity-no-description
+    question: clarity
+    persona: Edge_Case-99
+    base:
+      kind: feature
+      title: No description
+      description: ""
+      expect: Low
+    equivalent:
+      kind: feature
+      title: An idea
+      description: ""
+    faulty:
+      kind: feature
+      title: Search my reflections, not just article titles
+      description: I write a lot of reflections and can't find them later. The library search only matches titles, so I want it to match the text of my reflections too.
+      expect: High