diff --git a/engine/app/views/coplan/plans/history.html.erb b/engine/app/views/coplan/plans/history.html.erb
index aa44a61..172e95a 100644
--- a/engine/app/views/coplan/plans/history.html.erb
+++ b/engine/app/views/coplan/plans/history.html.erb
@@ -1,3 +1,3 @@
- <%= render partial: "coplan/plans/history", locals: { versions: @versions, plan: @plan } %>
+ <%= render partial: "coplan/plans/history", locals: { history_items: @history_items, plan: @plan } %>
diff --git a/engine/app/views/coplan/plans/show.html.erb b/engine/app/views/coplan/plans/show.html.erb
index 9c7e2f7..3abffca 100644
--- a/engine/app/views/coplan/plans/show.html.erb
+++ b/engine/app/views/coplan/plans/show.html.erb
@@ -20,7 +20,7 @@
diff --git a/engine/db/migrate/20260519000000_create_coplan_plan_events.rb b/engine/db/migrate/20260519000000_create_coplan_plan_events.rb
new file mode 100644
index 0000000..e7e6512
--- /dev/null
+++ b/engine/db/migrate/20260519000000_create_coplan_plan_events.rb
@@ -0,0 +1,19 @@
+class CreateCoplanPlanEvents < ActiveRecord::Migration[8.1]
+ def change
+ create_table :coplan_plan_events, id: { type: :string, limit: 36 } do |t|
+ t.string :plan_id, limit: 36, null: false
+ t.string :actor_id, limit: 36
+ t.string :actor_type, null: false
+ t.string :event_type, null: false
+ t.string :field
+ t.text :before_value
+ t.text :after_value
+ t.json :metadata
+ t.datetime :created_at, null: false
+
+ t.index :plan_id
+ t.index [:plan_id, :created_at]
+ t.index :event_type
+ end
+ end
+end
diff --git a/spec/factories/plan_events.rb b/spec/factories/plan_events.rb
new file mode 100644
index 0000000..97577e2
--- /dev/null
+++ b/spec/factories/plan_events.rb
@@ -0,0 +1,38 @@
+FactoryBot.define do
+ factory :plan_event, class: "CoPlan::PlanEvent" do
+ plan
+ actor_type { "human" }
+ event_type { "status_changed" }
+ field { "status" }
+ before_value { "considering" }
+ after_value { "developing" }
+ metadata { {} }
+
+ trait :title_changed do
+ event_type { "title_changed" }
+ field { "title" }
+ before_value { "Old title" }
+ after_value { "New title" }
+ end
+
+ trait :tag_added do
+ event_type { "tag_added" }
+ field { "tags" }
+ before_value { nil }
+ after_value { "payments" }
+ end
+
+ trait :reference_added do
+ event_type { "reference_added" }
+ field { "references" }
+ before_value { nil }
+ after_value { "https://github.com/squareup/example" }
+ metadata { { "title" => "Example repo", "reference_type" => "repository" } }
+ end
+
+ trait :system do
+ actor_type { "system" }
+ actor_id { nil }
+ end
+ end
+end
diff --git a/spec/models/plan_event_spec.rb b/spec/models/plan_event_spec.rb
new file mode 100644
index 0000000..ac57022
--- /dev/null
+++ b/spec/models/plan_event_spec.rb
@@ -0,0 +1,51 @@
+require "rails_helper"
+
+RSpec.describe CoPlan::PlanEvent, type: :model do
+ let(:plan) { create(:plan) }
+
+ describe "validations" do
+ it "requires actor_type" do
+ event = build(:plan_event, actor_type: nil)
+ expect(event).not_to be_valid
+ expect(event.errors[:actor_type]).to be_present
+ end
+
+ it "rejects unknown actor_type values" do
+ event = build(:plan_event, actor_type: "spider")
+ expect(event).not_to be_valid
+ expect(event.errors[:actor_type]).to be_present
+ end
+
+ it "requires event_type" do
+ event = build(:plan_event, event_type: nil)
+ expect(event).not_to be_valid
+ expect(event.errors[:event_type]).to be_present
+ end
+
+ it "rejects unknown event_type values" do
+ event = build(:plan_event, event_type: "exploded")
+ expect(event).not_to be_valid
+ expect(event.errors[:event_type]).to be_present
+ end
+ end
+
+ describe "#history_kind" do
+ it "is :event so the history feed can distinguish it from PlanVersion" do
+ expect(build(:plan_event).history_kind).to eq(:event)
+ end
+ end
+
+ describe "after_initialize" do
+ it "defaults metadata to an empty hash (per AGENTS.md JSON-column rule)" do
+ expect(CoPlan::PlanEvent.new.metadata).to eq({})
+ end
+ end
+
+ describe "association with plan" do
+ it "is configured to be destroyed when the plan is destroyed" do
+ reflection = CoPlan::Plan.reflect_on_association(:plan_events)
+ expect(reflection).to be_present
+ expect(reflection.options[:dependent]).to eq(:destroy)
+ end
+ end
+end
diff --git a/spec/requests/plan_events_spec.rb b/spec/requests/plan_events_spec.rb
new file mode 100644
index 0000000..122baa9
--- /dev/null
+++ b/spec/requests/plan_events_spec.rb
@@ -0,0 +1,128 @@
+require "rails_helper"
+
+# Integration-level verification that every mutation path that *should* record
+# a metadata event actually does. The point isn't to retest the LogEvent
+# service (that has its own spec) — it's to lock down the contract between
+# the mutation surfaces and the event log so future controllers don't quietly
+# drop the wiring.
+RSpec.describe "Plan metadata event logging", type: :request do
+ let(:user) { create(:coplan_user) }
+ let(:plan) { create(:plan, :considering, created_by_user: user, title: "Original") }
+
+ before { sign_in_as(user) }
+
+ describe "PATCH /plans/:id (web)" do
+ it "records a title_changed event when the title moves" do
+ expect {
+ patch plan_path(plan), params: { plan: { title: "Renamed" } }
+ }.to change { plan.plan_events.where(event_type: "title_changed").count }.by(1)
+
+ event = plan.plan_events.where(event_type: "title_changed").last
+ expect(event.before_value).to eq("Original")
+ expect(event.after_value).to eq("Renamed")
+ expect(event.actor_user).to eq(user)
+ end
+ end
+
+ describe "PATCH /plans/:id/status (web)" do
+ it "records a status_changed event when the status moves" do
+ expect {
+ patch update_status_plan_path(plan), params: { status: "developing" }
+ }.to change { plan.plan_events.where(event_type: "status_changed").count }.by(1)
+
+ event = plan.plan_events.where(event_type: "status_changed").last
+ expect(event.before_value).to eq("considering")
+ expect(event.after_value).to eq("developing")
+ end
+
+ it "does not record an event when the status doesn't actually change" do
+ expect {
+ patch update_status_plan_path(plan), params: { status: "considering" }
+ }.not_to change { plan.plan_events.count }
+ end
+ end
+
+ describe "POST /plans/:id/references (web)" do
+ it "records a reference_added event with the URL and metadata" do
+ expect {
+ post plan_references_path(plan), params: {
+ reference: { url: "https://github.com/squareup/example", title: "Example" }
+ }
+ }.to change { plan.plan_events.where(event_type: "reference_added").count }.by(1)
+
+ event = plan.plan_events.where(event_type: "reference_added").last
+ expect(event.after_value).to eq("https://github.com/squareup/example")
+ expect(event.metadata).to include("title" => "Example")
+ end
+ end
+
+ describe "DELETE /plans/:id/references/:id (web)" do
+ it "records a reference_removed event capturing the original URL" do
+ reference = plan.references.create!(url: "https://github.com/squareup/x", title: "X", reference_type: "repository", source: "explicit")
+
+ expect {
+ delete plan_reference_path(plan, reference)
+ }.to change { plan.plan_events.where(event_type: "reference_removed").count }.by(1)
+
+ event = plan.plan_events.where(event_type: "reference_removed").last
+ expect(event.before_value).to eq("https://github.com/squareup/x")
+ end
+ end
+
+ describe "PATCH /api/v1/plans/:id (API)" do
+ let(:raw_token) { CoPlan::ApiToken.generate_token }
+ let!(:token) { create(:api_token, user: user, raw_token: raw_token) }
+ let(:auth_headers) { { "Authorization" => "Bearer #{raw_token}" } }
+
+ it "records events for title, status, and tag diffs in a single request" do
+ plan.tag_names = ["existing"]
+
+ expect {
+ patch "/api/v1/plans/#{plan.id}", params: {
+ title: "API-renamed",
+ status: "developing",
+ tags: ["existing", "added"]
+ }, headers: auth_headers, as: :json
+ }.to change { plan.plan_events.count }.by(3)
+
+ expect(plan.plan_events.pluck(:event_type)).to contain_exactly(
+ "title_changed", "status_changed", "tag_added"
+ )
+ end
+
+ it "records tag_removed events for tags that disappear from the list" do
+ plan.tag_names = ["payments", "billing"]
+
+ expect {
+ patch "/api/v1/plans/#{plan.id}", params: {
+ tags: ["payments"]
+ }, headers: auth_headers, as: :json
+ }.to change { plan.plan_events.where(event_type: "tag_removed").count }.by(1)
+
+ removed = plan.plan_events.where(event_type: "tag_removed").last
+ expect(removed.before_value).to eq("billing")
+ end
+
+ it "records reference_added when a new reference is included in the update payload" do
+ expect {
+ patch "/api/v1/plans/#{plan.id}", params: {
+ references: [{ url: "https://docs.example.com/spec", title: "Spec" }]
+ }, headers: auth_headers, as: :json
+ }.to change { plan.plan_events.where(event_type: "reference_added").count }.by(1)
+ end
+ end
+
+ describe "Plan#history_items" do
+ it "interleaves content versions and metadata events, newest first" do
+ # The :plan factory already creates a revision-1 PlanVersion for us.
+ v1 = plan.plan_versions.first
+ v1.update_columns(created_at: 3.hours.ago)
+ e1 = create(:plan_event, plan: plan, event_type: "status_changed", created_at: 2.hours.ago)
+ v2 = create(:plan_version, plan: plan, revision: 2, created_at: 1.hour.ago)
+
+ items = plan.history_items
+ expect(items.map(&:id)).to eq([v2.id, e1.id, v1.id])
+ expect(items.map(&:history_kind)).to eq([:version, :event, :version])
+ end
+ end
+end
diff --git a/spec/services/plans/log_event_spec.rb b/spec/services/plans/log_event_spec.rb
new file mode 100644
index 0000000..b35daf9
--- /dev/null
+++ b/spec/services/plans/log_event_spec.rb
@@ -0,0 +1,71 @@
+require "rails_helper"
+
+RSpec.describe CoPlan::Plans::LogEvent do
+ let(:user) { create(:coplan_user) }
+ let(:plan) { create(:plan, created_by_user: user) }
+
+ describe ".call" do
+ it "creates a PlanEvent attributed to the actor" do
+ expect {
+ described_class.call(
+ plan: plan,
+ actor: user,
+ event_type: "status_changed",
+ before: "considering",
+ after: "developing"
+ )
+ }.to change { CoPlan::PlanEvent.count }.by(1)
+
+ event = CoPlan::PlanEvent.last
+ expect(event.plan).to eq(plan)
+ expect(event.actor_user).to eq(user)
+ expect(event.actor_type).to eq("human")
+ expect(event.event_type).to eq("status_changed")
+ expect(event.before_value).to eq("considering")
+ expect(event.after_value).to eq("developing")
+ end
+
+ it "infers a sensible default field per event_type when not provided" do
+ described_class.call(plan: plan, actor: user, event_type: "tag_added", after: "payments")
+ expect(CoPlan::PlanEvent.last.field).to eq("tags")
+ end
+
+ it "treats the actor as 'system' when no user is passed (e.g. backfill jobs)" do
+ described_class.call(plan: plan, actor: nil, event_type: "status_changed", before: "a", after: "b")
+ event = CoPlan::PlanEvent.last
+ expect(event.actor_type).to eq("system")
+ expect(event.actor_id).to be_nil
+ end
+
+ it "returns nil and does not persist when before == after for change events" do
+ # Call sites should be allowed to fire on every save without checking;
+ # the service no-ops when nothing actually changed.
+ expect {
+ described_class.call(plan: plan, actor: user, event_type: "status_changed", before: "considering", after: "considering")
+ }.not_to change { CoPlan::PlanEvent.count }
+ end
+
+ it "still records add/remove events even when one side is nil" do
+ described_class.call(plan: plan, actor: user, event_type: "tag_added", after: "payments")
+ described_class.call(plan: plan, actor: user, event_type: "reference_removed", before: "https://x")
+ expect(CoPlan::PlanEvent.count).to eq(2)
+ end
+
+ it "passes through structured metadata" do
+ described_class.call(
+ plan: plan,
+ actor: user,
+ event_type: "reference_added",
+ after: "https://github.com/example/repo",
+ metadata: { title: "Example", reference_type: "repository" }
+ )
+ event = CoPlan::PlanEvent.last
+ expect(event.metadata).to include("title" => "Example", "reference_type" => "repository")
+ end
+
+ it "coerces non-string before/after values to strings for storage" do
+ described_class.call(plan: plan, actor: user, event_type: "tag_added", after: 42)
+ expect(CoPlan::PlanEvent.last.after_value).to eq("42")
+ end
+ end
+end