anima-core 1.1.2 → 1.2.0

data/workflows/resume_handoff.md

@@ -1,6 +1,6 @@
 ---
 name: resume_handoff
-description: "Resume work from a handoff document with context analysis and validation."
+description: "Continue work left by a previous session — read its handoff, verify assumptions, and pick up where it stopped."
 ---
 
 # Resume work from a handoff document

data/workflows/review_pr.md

@@ -1,6 +1,6 @@
 ---
 name: review_pr
-description: "Multi-agent PR review with three modes: review, re-review, self-review."
+description: "All PR review operations — review, re-review, self-review, or address reviewer feedback."
 ---
 
 ## Modes
@@ -8,9 +8,14 @@ description: "Multi-agent PR review with three modes: review, re-review, self-re
 - **review** (default): Full review, present findings for approval before posting
 - **re-review**: Also load existing review feedback; verify previously requested changes were addressed
 - **self-review**: Fix findings directly in code instead of posting a review
+- **address-feedback**: Read reviewer comments, research the codebase, fix issues, reply to each comment on GitHub
 
 ## Process
 
+Your role is **orchestrator and judge**, not doer. You collect artifacts, delegate analysis to subagents, and apply judgment to their output. The subagents read the code and comments — you decide what to do about their findings. Your context budget is reserved for judgment, not for reading raw data.
+
+Steps are sequential — later steps depend on earlier results. Complete each step and wait for its results before starting the next. Skipping ahead without subagent results means the judgment layer in "Step 5: Merge Results" has nothing to work with. Only parallelize where explicitly marked (e.g., "spawn in parallel").
+
 ### Step 1: Gather PR Metadata
 
 ```bash
@@ -18,19 +23,27 @@ gh pr view <PR_NUMBER> --json number,title,body,url,headRefName,baseRefName
 ```
 
 Extract from PR body:
-- **Issue reference** (e.g., #123) — if found, fetch full issue details for requirements and acceptance criteria via `gh issue view`
+- **Issue reference** (e.g., #123) — fetch full issue details via `gh issue view` for requirements and acceptance criteria. You can't review a feature without knowing what was in the task description before it was implemented.
 - **Business context** — why this change is needed
 
-If re-review mode is activated, also save all existing review feedback to `/tmp/` without reading them:
+If re-review or address-feedback mode is activated, also save all existing review feedback to `/tmp/`:
+
+**Do not read these files — pass them to subagents by path only.** The subagents will read and analyze the content. Reading them here would consume context budget that the main agent needs for judgment in "Step 5: Merge Results".
 ```bash
 # Review verdicts and bodies (APPROVED, CHANGES_REQUESTED, COMMENTED)
-gh api repos/<OWNER>/<REPO>/pulls/<PR_NUMBER>/reviews | tee /tmp/pr_<NUMBER>_reviews.json | jq length
+gh api repos/<OWNER>/<REPO>/pulls/<PR_NUMBER>/reviews \
+  --jq '[.[] | {id, state, body, html_url, commit_id, submitted_at, author_association, user: .user.login}]' \
+  | tee /tmp/pr_<NUMBER>_reviews.json | toon
 
 # Inline review comments on specific diff lines
-gh api repos/<OWNER>/<REPO>/pulls/<PR_NUMBER>/comments | tee /tmp/pr_<NUMBER>_inline_comments.json | jq length
+gh api repos/<OWNER>/<REPO>/pulls/<PR_NUMBER>/comments \
+  --jq '[.[] | {id, pull_request_review_id, body, path, line, start_line, side, diff_hunk, commit_id, created_at, author_association, in_reply_to_id, user: .user.login}]' \
+  | tee /tmp/pr_<NUMBER>_inline_comments.json | toon
 
 # Conversation-level comments
-gh api repos/<OWNER>/<REPO>/issues/<PR_NUMBER>/comments | tee /tmp/pr_<NUMBER>_conversation.json | jq length
+gh api repos/<OWNER>/<REPO>/issues/<PR_NUMBER>/comments \
+  --jq '[.[] | {id, body, html_url, created_at, updated_at, author_association, user: .user.login}]' \
+  | tee /tmp/pr_<NUMBER>_conversation.json | toon
 ```
 
 ### Step 2: Fetch and Save Diff
@@ -71,9 +84,11 @@ specialist: thoughts-analyzer
 Prompt: "What do we know about <ticket reference and title from Step 1>? What decisions, constraints, and trade-offs should reviewers be aware of?"
 ```
 
-**Wait for this specialist to complete before proceeding.**
+**Wait for this specialist to complete, then proceed to "Step 4-a: Spawn Review Subagents".**
+
+### Step 4-a: Spawn Review Subagents
 
-### Step 4: Spawn Review Subagents
+If address-feedback mode is activated, skip to "Step 4-b: Spawn Codebase Research Subagents (address-feedback)" below.
 
 Spawn all five review subagents **in parallel** using `spawn_subagent`. Each receives:
 - Path to the diff file in `/tmp/`
@@ -218,13 +233,21 @@ Read the diff from: /tmp/pr_<number>_diff.txt
 - Method and class naming clarity
 - Missing YARD documentation on public interfaces
 - Complex logic lacking explanatory comments
-- Changelog updates for notable changes
 - Misleading or outdated comments
 - Magic numbers or strings needing constants
 
 Output: List findings tagged [major], [minor], or [nit] with file:line references."
 ```
 
+### Step 4-b: Spawn Codebase Research Subagents (address-feedback)
+
+Unless address-feedback mode is activated, skip to "Step 5: Merge Results" below.
+
+Spawn **codebase-analyzer** and **codebase-pattern-finder** specialists in parallel. Each receives:
+- Paths to comment files and diff file in `/tmp/`
+- Historical context (from Step 3)
+- Any additional instructions from the user's input
+
 ### Step 5: Merge Results
 
 After all subagents complete, compile findings into a unified review.
@@ -235,6 +258,12 @@ For each finding, evaluate:
 - **Real-world probability** — Can this actually happen in practice, or is it purely theoretical? A race condition that requires two users to open a personal link within the same millisecond is not a real issue.
 - **Cost-benefit** — Does the fix add more complexity than the problem warrants? If the "fix" makes the code harder to read without solving a problem a human would encounter, drop it.
 - **Scope** — Review fixes should improve code you're touching, not introduce new artifacts. Clean up, don't build out.
+- **Design intent** — Was this a deliberate choice? A finding that flags a conscious trade-off documented in historical context is a decline, not a fix.
+
+Then classify:
+- **Accept & fix** — finding valid, apply the suggested fix or a better one
+- **Accept, different approach** — finding valid, but context points to a different solution
+- **Decline** — not valid in context, or a deliberate design choice
 
 Then compile:
 
@@ -249,7 +278,9 @@ Determine verdict:
 
 ### Step 6: Finalize
 
-If self-review mode is activated, skip to **Self-review** below.
+Your role changes from orchestrator to doer. You now have the judgment results — act on them.
+
+If self-review or address-feedback mode is activated, skip to "Step 7: Apply Fixes" below.
 
 #### Present and Post (review / re-review)
 
@@ -271,21 +302,52 @@ gh pr review <PR_NUMBER> --approve --body "<review body>"
 gh pr review <PR_NUMBER> --request-changes --body "<review body>"
 ```
 
-#### Self-review
-
-Instead of presenting and posting, act on the findings:
+### Step 7: Apply Fixes (self-review / address-feedback)
 
 1. **Fix findings** — Address [major] and [minor] issues directly in code. Apply [nit]s at own discretion.
 2. **Commit and push** — Commit the fixes with a descriptive message and push to the PR branch.
-3. **Assign reviewer** — Assign the user and request review from anyone mentioned in additional instructions.
-4. **Wait for CI** — Monitor CI status. Once green, mark the PR as ready for review.
+3. **Monitor CI** — Wait for CI to pass. The PR cannot be finalized until CI is green.
+
+```bash
+gh pr checks <PR_NUMBER> --watch
+```
+
+Fixes are pushed and CI is green. Now finalize the PR — proceed to the section matching your mode below.
+
+#### Self-Review Finalization
+
+Assign the user and request review from anyone mentioned in additional instructions. Then mark the PR as ready for human review.
 
 ```bash
 gh pr edit <PR_NUMBER> --add-assignee <user> --add-reviewer <reviewer>
-# once CI is green:
 gh pr ready <PR_NUMBER>
 ```
 
+Done when the PR is marked ready and appears in the reviewer's queue.
+
+#### Address-Feedback Finalization
+
+Reply to each reviewer comment on GitHub with the resolution:
+- Accept & fix: "Fixed in `<commit sha>`."
+- Accept, different approach: "Agreed with the concern. Took a different approach: [explanation]. Fixed in `<commit sha>`."
+- Decline: "This was intentional — [rationale]."
+
+```bash
+# Reply to an inline comment
+gh api repos/<OWNER>/<REPO>/pulls/<PR_NUMBER>/comments/<COMMENT_ID>/replies -f body="<reply>"
+
+# Reply to a conversation-level comment
+gh api repos/<OWNER>/<REPO>/issues/<PR_NUMBER>/comments -f body="<reply>"
+```
+
+Then request re-review from the original reviewers:
+
+```bash
+gh pr edit <PR_NUMBER> --add-reviewer <original_reviewer>
+```
+
+Done when all comments are answered and re-review is requested.
+
 ## Posted Review Format
 
 ```markdown

data/workflows/thoughts_init.md

@@ -1,6 +1,6 @@
 ---
 name: thoughts_init
-description: "Initialize the thoughts system for the current repository."
+description: "Bootstrap ./thoughts for a new project that doesn't have one yet."
 ---
 
 # Initialize Thoughts System

data/workflows/validate_plan.md

@@ -1,6 +1,6 @@
 ---
 name: validate_plan
-description: "Validate implementation against plan, verify success criteria, and identify issues."
+description: "Check whether the implementation satisfies the plan — compare success criteria against what was actually built."
 ---
 
 # Validate Plan

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: anima-core
 version: !ruby/object:Gem::Version
-  version: 1.1.2
+  version: 1.2.0
 platform: ruby
 authors:
 - Yevhenii Hurin
@@ -259,7 +259,7 @@ files:
 - app/controllers/application_controller.rb
 - app/decorators/agent_message_decorator.rb
 - app/decorators/application_decorator.rb
-- app/decorators/event_decorator.rb
+- app/decorators/message_decorator.rb
 - app/decorators/system_message_decorator.rb
 - app/decorators/tool_call_decorator.rb
 - app/decorators/tool_decorator.rb
@@ -269,15 +269,15 @@ files:
 - app/jobs/agent_request_job.rb
 - app/jobs/analytical_brain_job.rb
 - app/jobs/application_job.rb
-- app/jobs/count_event_tokens_job.rb
+- app/jobs/count_message_tokens_job.rb
 - app/jobs/mneme_job.rb
 - app/jobs/passive_recall_job.rb
 - app/models/application_record.rb
-- app/models/concerns/event/broadcasting.rb
-- app/models/event.rb
+- app/models/concerns/message/broadcasting.rb
 - app/models/goal.rb
-- app/models/goal_pinned_event.rb
-- app/models/pinned_event.rb
+- app/models/goal_pinned_message.rb
+- app/models/message.rb
+- app/models/pinned_message.rb
 - app/models/session.rb
 - app/models/snapshot.rb
 - bin/jobs
@@ -323,6 +323,7 @@ files:
 - db/migrate/20260321120000_create_pinned_events.rb
 - db/migrate/20260321140000_create_events_fts_index.rb
 - db/migrate/20260321140100_add_recalled_event_ids_to_sessions.rb
+- db/migrate/20260326180000_rename_event_to_message.rb
 - db/queue_schema.rb
 - db/seeds.rb
 - exe/anima
@@ -377,7 +378,7 @@ files:
 - lib/mneme/passive_recall.rb
 - lib/mneme/runner.rb
 - lib/mneme/search.rb
-- lib/mneme/tools/attach_events_to_goals.rb
+- lib/mneme/tools/attach_messages_to_goals.rb
 - lib/mneme/tools/everything_ok.rb
 - lib/mneme/tools/save_snapshot.rb
 - lib/providers/anthropic.rb
@@ -389,10 +390,10 @@ files:
 - lib/tools/bash.rb
 - lib/tools/edit.rb
 - lib/tools/mcp_tool.rb
+- lib/tools/open_issue.rb
 - lib/tools/read.rb
 - lib/tools/registry.rb
 - lib/tools/remember.rb
-- lib/tools/request_feature.rb
 - lib/tools/spawn_specialist.rb
 - lib/tools/spawn_subagent.rb
 - lib/tools/subagent_prompts.rb

data/app/jobs/count_event_tokens_job.rb

@@ -1,39 +0,0 @@
-# frozen_string_literal: true
-
-# Counts tokens in an event's payload via the Anthropic API and
-# caches the result on the event record. Enqueued automatically
-# after each LLM event is created.
-class CountEventTokensJob < ApplicationJob
-  queue_as :default
-
-  retry_on Providers::Anthropic::Error, wait: :polynomially_longer, attempts: 3
-  discard_on ActiveRecord::RecordNotFound
-
-  # @param event_id [Integer] the Event record to count tokens for
-  def perform(event_id)
-    event = Event.find(event_id)
-    return if already_counted?(event)
-
-    provider = Providers::Anthropic.new
-    messages = [{role: event.api_role, content: event.payload["content"].to_s}]
-
-    token_count = provider.count_tokens(
-      model: Anima::Settings.model,
-      messages: messages
-    )
-
-    # Guard against parallel jobs: reload and re-check before writing.
-    # Uses update! (not update_all) so {Event::Broadcasting} after_update_commit
-    # broadcasts the updated token count to connected clients.
-    event.reload
-    return if already_counted?(event)
-
-    event.update!(token_count: token_count)
-  end
-
-  private
-
-  def already_counted?(event)
-    event.token_count > 0
-  end
-end

data/app/models/event.rb

@@ -1,110 +0,0 @@
-# frozen_string_literal: true
-
-# A persisted record of something that happened during a session.
-# Events are the single source of truth for conversation history —
-# there is no separate chat log, only events attached to a session.
-#
-# @!attribute event_type
-#   @return [String] one of {TYPES}: system_message, user_message,
-#     agent_message, tool_call, tool_response
-# @!attribute payload
-#   @return [Hash] event-specific data (content, tool_name, tool_input, etc.)
-# @!attribute timestamp
-#   @return [Integer] nanoseconds since epoch (Process::CLOCK_REALTIME)
-# @!attribute token_count
-#   @return [Integer] cached token count for this event's payload (0 until counted)
-# @!attribute tool_use_id
-#   @return [String, nil] Anthropic-assigned ID correlating tool_call and tool_response
-class Event < ApplicationRecord
-  include Event::Broadcasting
-
-  TYPES = %w[system_message user_message agent_message tool_call tool_response].freeze
-  LLM_TYPES = %w[user_message agent_message].freeze
-  CONTEXT_TYPES = %w[system_message user_message agent_message tool_call tool_response].freeze
-  CONVERSATION_TYPES = %w[user_message agent_message system_message].freeze
-  THINK_TOOL = "think"
-  PENDING_STATUS = "pending"
-
-  ROLE_MAP = {"user_message" => "user", "agent_message" => "assistant"}.freeze
-
-  # Heuristic: average bytes per token for English prose.
-  BYTES_PER_TOKEN = 4
-
-  belongs_to :session
-  has_many :pinned_events, dependent: :destroy
-
-  validates :event_type, presence: true, inclusion: {in: TYPES}
-  validates :payload, presence: true
-  validates :timestamp, presence: true
-
-  after_create :schedule_token_count, if: :llm_message?
-
-  # @!method self.llm_messages
-  #   Events that represent conversation turns sent to the LLM API.
-  #   @return [ActiveRecord::Relation]
-  scope :llm_messages, -> { where(event_type: LLM_TYPES) }
-
-  # @!method self.context_events
-  #   Events included in the LLM context window (messages + tool interactions).
-  #   @return [ActiveRecord::Relation]
-  scope :context_events, -> { where(event_type: CONTEXT_TYPES) }
-
-  # @!method self.pending
-  #   User messages queued during active agent processing, not yet sent to LLM.
-  #   @return [ActiveRecord::Relation]
-  scope :pending, -> { where(status: PENDING_STATUS) }
-
-  # @!method self.deliverable
-  #   Events eligible for LLM context (excludes pending messages).
-  #   NULL status means delivered/processed — the only excluded value is "pending".
-  #   @return [ActiveRecord::Relation]
-  scope :deliverable, -> { where(status: nil) }
-
-  # Maps event_type to the Anthropic Messages API role.
-  # @return [String] "user" or "assistant"
-  def api_role
-    ROLE_MAP.fetch(event_type)
-  end
-
-  # @return [Boolean] true if this event represents an LLM conversation turn
-  def llm_message?
-    event_type.in?(LLM_TYPES)
-  end
-
-  # @return [Boolean] true if this event is part of the LLM context window
-  def context_event?
-    event_type.in?(CONTEXT_TYPES)
-  end
-
-  # @return [Boolean] true if this is a pending message not yet sent to the LLM
-  def pending?
-    status == PENDING_STATUS
-  end
-
-  # @return [Boolean] true if this is a conversation event (user/agent/system message)
-  #   or a think tool_call — the events Mneme treats as "conversation" for boundary tracking
-  def conversation_or_think?
-    event_type.in?(CONVERSATION_TYPES) ||
-      (event_type == "tool_call" && payload["tool_name"] == THINK_TOOL)
-  end
-
-  # Heuristic token estimate: ~4 bytes per token for English prose.
-  # Tool events are estimated from the full payload JSON since tool_input
-  # and tool metadata contribute to token count. Messages use content only.
-  #
-  # @return [Integer] estimated token count (at least 1)
-  def estimate_tokens
-    text = if event_type.in?(%w[tool_call tool_response])
-      payload.to_json
-    else
-      payload["content"].to_s
-    end
-    [(text.bytesize / BYTES_PER_TOKEN.to_f).ceil, 1].max
-  end
-
-  private
-
-  def schedule_token_count
-    CountEventTokensJob.perform_later(id)
-  end
-end

data/app/models/goal_pinned_event.rb

@@ -1,11 +0,0 @@
-# frozen_string_literal: true
-
-# Join record linking a {Goal} to a {PinnedEvent}. Many-to-many: one event
-# can be pinned to multiple Goals, and one Goal can reference multiple pins.
-# When the last Goal referencing a pin completes, the pin is released.
-class GoalPinnedEvent < ApplicationRecord
-  belongs_to :goal
-  belongs_to :pinned_event
-
-  validates :pinned_event_id, uniqueness: {scope: :goal_id}
-end

data/app/models/pinned_event.rb

@@ -1,41 +0,0 @@
-# frozen_string_literal: true
-
-# A conversation event pinned to one or more Goals by Mneme to protect it
-# from viewport eviction. Pinned events appear in the Goals section of
-# the viewport, giving the main agent access to critical context that
-# would otherwise scroll out of the sliding window.
-#
-# Pinning is goal-scoped: when all Goals referencing a pin complete,
-# the pin is automatically released (reference-counted cleanup).
-#
-# @!attribute display_text
-#   @return [String] truncated event content (~200 chars) shown in the Goals section
-class PinnedEvent < ApplicationRecord
-  # Display text limit — enough to recognize content, cheap on tokens.
-  MAX_DISPLAY_TEXT_LENGTH = 200
-
-  belongs_to :event
-
-  has_many :goal_pinned_events, dependent: :destroy
-  has_many :goals, through: :goal_pinned_events
-
-  validates :display_text, presence: true, length: {maximum: MAX_DISPLAY_TEXT_LENGTH}
-  validates :event_id, uniqueness: true
-
-  # Pinned events with no remaining active goals — safe to release.
-  #
-  # @return [ActiveRecord::Relation]
-  scope :orphaned, -> {
-    where.not(
-      "EXISTS (SELECT 1 FROM goal_pinned_events gpe " \
-      "JOIN goals ON goals.id = gpe.goal_id " \
-      "WHERE gpe.pinned_event_id = pinned_events.id " \
-      "AND goals.status = 'active')"
-    )
-  }
-
-  # @return [Integer] token cost estimate for viewport budget accounting
-  def token_cost
-    [(display_text.bytesize / Event::BYTES_PER_TOKEN.to_f).ceil, 1].max
-  end
-end

data/lib/mneme/tools/attach_events_to_goals.rb

@@ -1,107 +0,0 @@
-# frozen_string_literal: true
-
-module Mneme
-  module Tools
-    # Pins critical events to active Goals so they survive viewport eviction.
-    # Mneme calls this when it sees important events (user instructions, key
-    # decisions, critical corrections) approaching the eviction zone.
-    #
-    # Events are pinned via a many-to-many join: one event can be attached
-    # to multiple Goals. When all referencing Goals complete, the pin is
-    # automatically released (reference-counted cleanup in {Goal#release_orphaned_pins!}).
-    class AttachEventsToGoals < ::Tools::Base
-      def self.tool_name = "attach_events_to_goals"
-
-      def self.description = "Pin critical events to active goals so they survive " \
-        "viewport eviction. Use this for events that are too important to lose — " \
-        "exact user instructions, key decisions, critical corrections. " \
-        "Events stay pinned until all attached goals complete."
-
-      def self.input_schema
-        {
-          type: "object",
-          properties: {
-            event_ids: {
-              type: "array",
-              items: {type: "integer"},
-              description: "Database IDs of events to pin (from `event N` prefixes in the viewport)"
-            },
-            goal_ids: {
-              type: "array",
-              items: {type: "integer"},
-              description: "IDs of active goals to attach the events to"
-            }
-          },
-          required: %w[event_ids goal_ids]
-        }
-      end
-
-      # @param main_session [Session] the session being observed
-      def initialize(main_session:, **)
-        @session = main_session
-      end
-
-      # @param input [Hash<String, Object>] with "event_ids" and "goal_ids"
-      # @return [String] confirmation with link count, or error description
-      def execute(input)
-        event_ids = Array(input["event_ids"]).map(&:to_i).uniq
-        goal_ids = Array(input["goal_ids"]).map(&:to_i).uniq
-
-        return "Error: event_ids cannot be empty" if event_ids.empty?
-        return "Error: goal_ids cannot be empty" if goal_ids.empty?
-
-        events = @session.events.where(id: event_ids)
-        goals = @session.goals.active.where(id: goal_ids)
-
-        missing_events = event_ids - events.pluck(:id)
-        inactive_goal_ids = goal_ids - goals.pluck(:id)
-
-        errors = []
-        errors << "Events not found: #{missing_events.join(", ")}" if missing_events.any?
-
-        if inactive_goal_ids.any?
-          completed_ids = @session.goals.completed.where(id: inactive_goal_ids).pluck(:id)
-          not_found_ids = inactive_goal_ids - completed_ids
-          errors << "Goals already completed: #{completed_ids.join(", ")}" if completed_ids.any?
-          errors << "Goals not found: #{not_found_ids.join(", ")}" if not_found_ids.any?
-        end
-
-        return "Error: #{errors.join("; ")}" if errors.any?
-
-        attached = attach(events, goals)
-        "Pinned #{attached} event-goal links"
-      end
-
-      private
-
-      def attach(events, goals)
-        events.sum do |event|
-          pinned = find_or_create_pinned_event(event)
-          link_to_goals(pinned, goals)
-        end
-      end
-
-      def link_to_goals(pinned, goals)
-        goals.each { |goal| GoalPinnedEvent.find_or_create_by!(goal: goal, pinned_event: pinned) }
-        goals.size
-      end
-
-      def find_or_create_pinned_event(event)
-        PinnedEvent.find_or_create_by!(event: event) do |pe|
-          pe.display_text = truncate_event_content(event)
-        end
-      end
-
-      def truncate_event_content(event)
-        content = event.payload&.dig("content").to_s.strip
-        content = "event #{event.id}" if content.empty?
-
-        if content.length > PinnedEvent::MAX_DISPLAY_TEXT_LENGTH
-          content[0, PinnedEvent::MAX_DISPLAY_TEXT_LENGTH - 1] + "…"
-        else
-          content
-        end
-      end
-    end
-  end
-end