RubyGems - cardinal-ai - Versions diffs - 0.0.1 → 0.2.3 - Mend

cardinal-ai 0.0.1 → 0.2.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (107) hide show

checksums.yaml +4 -4
data/LICENSE +21 -0
data/README.md +50 -29
data/Rakefile +6 -0
data/app/assets/stylesheets/application.css +10 -0
data/app/assets/stylesheets/cardinal.css +514 -0
data/app/controllers/application_controller.rb +7 -0
data/app/controllers/boards_controller.rb +5 -0
data/app/controllers/cards_controller.rb +129 -0
data/app/controllers/columns_controller.rb +95 -0
data/app/controllers/messages_controller.rb +25 -0
data/app/controllers/runs_controller.rb +58 -0
data/app/helpers/application_helper.rb +35 -0
data/app/javascript/application.js +2 -0
data/app/javascript/controllers/application.js +7 -0
data/app/javascript/controllers/autosave_controller.js +28 -0
data/app/javascript/controllers/board_column_controller.js +96 -0
data/app/javascript/controllers/clipboard_controller.js +18 -0
data/app/javascript/controllers/composer_controller.js +10 -0
data/app/javascript/controllers/index.js +3 -0
data/app/javascript/controllers/modal_controller.js +43 -0
data/app/javascript/controllers/scroll_controller.js +44 -0
data/app/javascript/controllers/tags_controller.js +49 -0
data/app/javascript/controllers/theme_controller.js +43 -0
data/app/javascript/controllers/tooltip_controller.js +37 -0
data/app/jobs/ai_task_job.rb +26 -0
data/app/jobs/application_job.rb +7 -0
data/app/jobs/assistant_reply_job.rb +132 -0
data/app/jobs/mark_pr_ready_job.rb +18 -0
data/app/jobs/merge_pr_job.rb +27 -0
data/app/jobs/resume_run_job.rb +30 -0
data/app/jobs/start_run_job.rb +13 -0
data/app/mailers/application_mailer.rb +4 -0
data/app/models/agent_session.rb +8 -0
data/app/models/application_record.rb +3 -0
data/app/models/artifact.rb +8 -0
data/app/models/board.rb +60 -0
data/app/models/card.rb +83 -0
data/app/models/column.rb +83 -0
data/app/models/event.rb +44 -0
data/app/models/run.rb +28 -0
data/app/services/agent/runner.rb +379 -0
data/app/services/agent/workspace.rb +138 -0
data/app/services/card_transition.rb +97 -0
data/app/services/claude_cli.rb +89 -0
data/app/services/rules/compiler.rb +55 -0
data/app/services/rules.rb +67 -0
data/app/services/run_sweeper.rb +52 -0
data/app/views/boards/show.html.erb +79 -0
data/app/views/cards/_card.html.erb +48 -0
data/app/views/cards/_detail.html.erb +190 -0
data/app/views/cards/_tag_picker.html.erb +12 -0
data/app/views/cards/new.html.erb +35 -0
data/app/views/cards/show.html.erb +3 -0
data/app/views/columns/_column.html.erb +25 -0
data/app/views/columns/edit.html.erb +126 -0
data/app/views/events/_event.html.erb +29 -0
data/app/views/layouts/application.html.erb +46 -0
data/app/views/layouts/mailer.html.erb +13 -0
data/app/views/layouts/mailer.text.erb +1 -0
data/app/views/pwa/manifest.json.erb +22 -0
data/app/views/pwa/service-worker.js +26 -0
data/bin/rails +4 -0
data/bin/rake +4 -0
data/cardinal.md +686 -0
data/config/application.rb +60 -0
data/config/boot.rb +13 -0
data/config/bundler-audit.yml +5 -0
data/config/cable.yml +13 -0
data/config/ci.rb +20 -0
data/config/credentials.yml.enc +1 -0
data/config/database.yml +31 -0
data/config/environment.rb +5 -0
data/config/environments/development.rb +78 -0
data/config/environments/production.rb +89 -0
data/config/environments/test.rb +53 -0
data/config/importmap.rb +6 -0
data/config/initializers/assets.rb +7 -0
data/config/initializers/cardinal_bootstrap.rb +12 -0
data/config/initializers/cardinal_instance.rb +20 -0
data/config/initializers/content_security_policy.rb +29 -0
data/config/initializers/filter_parameter_logging.rb +8 -0
data/config/initializers/inflections.rb +16 -0
data/config/initializers/run_sweeper.rb +17 -0
data/config/locales/en.yml +31 -0
data/config/puma.rb +42 -0
data/config/routes.rb +22 -0
data/config/storage.yml +27 -0
data/config.ru +6 -0
data/db/migrate/20260703000001_create_cardinal_schema.rb +78 -0
data/db/migrate/20260703000002_add_agent_runner_fields.rb +7 -0
data/db/migrate/20260704000001_add_parent_to_cards.rb +5 -0
data/db/migrate/20260704000002_add_assistant_session_to_cards.rb +5 -0
data/db/seeds.rb +19 -0
data/docker/agent/Dockerfile +16 -0
data/exe/cardinal +111 -0
data/lib/cardinal/version.rb +1 -1
data/public/400.html +135 -0
data/public/404.html +135 -0
data/public/406-unsupported-browser.html +135 -0
data/public/422.html +135 -0
data/public/500.html +135 -0
data/public/icon.png +0 -0
data/public/icon.svg +3 -0
data/public/robots.txt +1 -0
data/vendor/javascript/sortablejs.js +3378 -0
metadata +235 -9

data/app/javascript/controllers/theme_controller.js ADDED Viewed

@@ -0,0 +1,43 @@
+import { Controller } from "@hotwired/stimulus"
+// Toggles between dark (default) and light themes by setting data-theme on
+// <html> and persisting the choice to localStorage. The initial theme is
+// applied by an inline boot script in the <head> to avoid a flash of the
+// wrong theme; this controller only handles the toggle and keeps its label
+// in sync with the current theme.
+export default class extends Controller {
+  static targets = ["label"]
+  connect() {
+    this.render()
+  }
+  toggle() {
+    const next = this.current === "light" ? "dark" : "light"
+    // Dark is the default, so we only persist/mark an explicit light choice.
+    if (next === "light") {
+      document.documentElement.setAttribute("data-theme", "light")
+      localStorage.setItem("theme", "light")
+    } else {
+      document.documentElement.removeAttribute("data-theme")
+      localStorage.setItem("theme", "dark")
+    }
+    this.render()
+  }
+  get current() {
+    return document.documentElement.getAttribute("data-theme") === "light" ? "light" : "dark"
+  }
+  render() {
+    // Show the action the button will take, not the current state.
+    const toLight = this.current === "dark"
+    const text = toLight ? "☀ Light" : "☾ Dark"
+    if (this.hasLabelTarget) {
+      this.labelTarget.textContent = text
+    } else {
+      this.element.textContent = text
+    }
+    this.element.setAttribute("aria-label", toLight ? "Switch to light mode" : "Switch to dark mode")
+  }
+}

data/app/javascript/controllers/tooltip_controller.js ADDED Viewed

@@ -0,0 +1,37 @@
+import { Controller } from "@hotwired/stimulus"
+// (i) tooltips. Rendered into document.body with fixed positioning so they
+// can never be clipped by modal overflow; clamped to the viewport.
+export default class extends Controller {
+  static values = { text: String }
+  show() {
+    this.hide()
+    this.pop = document.createElement("div")
+    this.pop.className = "tooltip-pop"
+    this.pop.textContent = this.textValue
+    document.body.appendChild(this.pop)
+    const icon = this.element.getBoundingClientRect()
+    const pop = this.pop.getBoundingClientRect()
+    const margin = 8
+    let left = icon.left + icon.width / 2 - pop.width / 2
+    left = Math.max(margin, Math.min(left, window.innerWidth - pop.width - margin))
+    let top = icon.top - pop.height - margin
+    if (top < margin) top = icon.bottom + margin
+    this.pop.style.left = `${left}px`
+    this.pop.style.top = `${top}px`
+  }
+  hide() {
+    this.pop?.remove()
+    this.pop = null
+  }
+  disconnect() {
+    this.hide()
+  }
+}

data/app/jobs/ai_task_job.rb ADDED Viewed

@@ -0,0 +1,26 @@
+# A maintenance agent (cardinal.md §17): one bounded claude CLI call fired by
+# a column rule. The prompt template may reference the card via %{title},
+# %{description}, %{conversation}. Output lands on the timeline as an
+# assistant_message. Distinct from the worker agent — no workspace, no tools.
+class AiTaskJob < ApplicationJob
+  queue_as :default
+  def perform(card_id, prompt_template, model = nil)
+    card = Card.find(card_id)
+    return if prompt_template.blank? || !ClaudeCli.available?
+    prompt = format(prompt_template,
+                    title: card.title,
+                    description: card.description.to_s,
+                    conversation: card.events.conversation.filter_map(&:text).last(30).join("\n\n"))
+    text = ClaudeCli.prompt(
+      prompt,
+      system: "You are a maintenance agent on a Cardinal board performing one bounded task on card ##{card.number}. Be concise; your output is posted directly to the card's timeline.",
+      model: model.presence || AssistantReplyJob::FALLBACK_MODEL
+    )
+    card.log!("assistant_message", actor: "assistant", text: text) if text.present?
+  rescue ClaudeCli::Error => e
+    card.log!("error", text: "The maintenance agent #{e.message}.", detail: e.detail)
+  end
+end

data/app/jobs/application_job.rb ADDED Viewed

@@ -0,0 +1,7 @@
+class ApplicationJob < ActiveJob::Base
+  # Automatically retry jobs that encountered a deadlock
+  # retry_on ActiveRecord::Deadlocked
+  # Most jobs are safe to ignore if the underlying records are no longer available
+  # discard_on ActiveJob::DeserializationError
+end

data/app/jobs/assistant_reply_job.rb ADDED Viewed

@@ -0,0 +1,132 @@
+# The shared planning assistant (cardinal.md §5): a CONTINUING claude session
+# per card (assistant_session_id) — context and repo exploration carry across
+# replies instead of being re-paid per message. Falls back to a fresh session
+# (with the transcript embedded) if the stored session can't be resumed.
+class AssistantReplyJob < ApplicationJob
+  queue_as :default
+  FALLBACK_MODEL = "claude-haiku-4-5-20251001".freeze
+  MAX_TURNS = 20
+  ROLE_REMINDER = "Reminder: you are the PLANNING assistant. You refine cards and write briefs — " \
+                  "you never implement. No code files, no full implementations, no 'run these " \
+                  "commands'. Your tools are READ-ONLY: you are physically incapable of modifying " \
+                  "any file, so NEVER claim to have made, applied, or reverted a change — any such " \
+                  "claim would be false. If the user approves an approach, finalize the " \
+                  "Ready-for-execution brief and tell them to drag the card to a work column.".freeze
+  KICKOFF_TURN = <<~MSG.freeze
+    This card just entered the Planning column. Open the discussion: greet me in one short
+    sentence, then ask the 2-3 most important clarifying questions that would make THIS
+    card execution-ready. Be specific to the card's actual content — never generic. If the
+    card is already crystal clear, say so and propose a "Ready for execution" brief instead.
+  MSG
+  # kickoff: true generates the opening message when a card enters planning.
+  def perform(card, kickoff: false)
+    unless ClaudeCli.available?
+      card.log!("assistant_message", actor: "assistant",
+                text: "I'm here to help shape this card. What's the goal, and how will we know it's done? (Install the claude CLI for a smarter assistant.)")
+      return
+    end
+    reply, session_id = converse(card, kickoff:)
+    card.update!(assistant_session_id: session_id) if session_id.present?
+    card.log!("assistant_message", actor: "assistant", text: reply) if reply.present?
+  rescue ClaudeCli::Error => e
+    card.log!("error", text: "The planning assistant #{e.message}.", detail: e.detail)
+  end
+  private
+  # Invariant: the assistant's session must never hold less of the timeline
+  # than the user's screen shows. Kickoffs seed ALL prior conversation (notes
+  # made before Planning included); resumes send everything said since the
+  # assistant's last reply, not just the latest message.
+  def converse(card, kickoff:)
+    repo = card.board.local_path.presence
+    common = { model: card.column.model.presence || FALLBACK_MODEL,
+               tools: repo ? "Read,Glob,Grep" : nil,
+               cwd: repo, max_turns: MAX_TURNS, with_session: true }
+    if !kickoff && card.assistant_session_id.present?
+      begin
+        # ROLE_REMINDER rides every resume: long sessions drift, and an
+        # affirming reply ("yes, that approach") must not escalate the
+        # planner into implementing.
+        return ClaudeCli.prompt(unheard_messages(card), resume: card.assistant_session_id,
+                                system: ROLE_REMINDER, **common)
+      rescue ClaudeCli::Error
+        card.update!(assistant_session_id: nil) # stale/expired — start fresh below
+      end
+    end
+    opener = kickoff ? kickoff_prompt(card) : transcript_prompt(card)
+    ClaudeCli.prompt(opener, system: system_prompt(card), **common)
+  end
+  def kickoff_prompt(card)
+    prior = conversation_turns(card)
+    return KICKOFF_TURN if prior.empty?
+    "#{KICKOFF_TURN}\n\nThe card already carries conversation/notes from before it " \
+    "entered Planning — treat these as things I have already told you:\n\n#{prior.join("\n\n")}"
+  end
+  # Everything the user said since the assistant last spoke — never just the
+  # latest message (bursts and between-column notes must not be dropped).
+  def unheard_messages(card)
+    last_reply_id = card.events.where(kind: "assistant_message").maximum(:id) || 0
+    texts = card.events.where(kind: "user_message").where("id > ?", last_reply_id)
+                .order(:id).filter_map(&:text)
+    texts.presence&.join("\n\n") || card.events.where(kind: "user_message").order(:id).last&.text.to_s
+  end
+  def system_prompt(card)
+    <<~PROMPT
+      You are the planning assistant on Cardinal, a Kanban board where cards become AI \
+      worker agents once they enter an execution column. You are helping the user shape \
+      card ##{card.number}: "#{card.title}".
+      #{"Card description:\n#{card.description}\n" if card.description.present?}
+      #{"Column instructions: #{card.column.instructions}\n" if card.column.instructions.present?}
+      Your job is to refine this card until it is ready for an execution agent: clarify \
+      the goal, surface hidden requirements, bound the scope, and drive toward crisp \
+      acceptance criteria. Be concise and concrete — a few sentences or a short list per \
+      reply. When the card feels well-defined, offer a short "Ready for execution" brief \
+      summarizing goal, scope, and acceptance criteria.
+      HARD BOUNDARY: you plan; you NEVER implement. Do not write code files, produce \
+      full-file implementations, or tell the user to run commands to apply changes — \
+      even if asked. A separate worker agent implements after the card leaves Planning. \
+      Small illustrative snippets (a few lines) inside a discussion are fine; anything \
+      resembling a deliverable is not. When the user approves an approach or says "do \
+      it", your move is: finalize the Ready-for-execution brief and tell them to drag \
+      the card onward.
+      Your tools are READ-ONLY (Read/Glob/Grep). You are physically incapable of \
+      changing any file. Never state or imply that you made, applied, or reverted a \
+      change — such a claim is always false.
+      #{"You have READ-ONLY access to the board's repository (Read/Glob/Grep; you are in \
+      its root). Ground your questions and advice in the actual code whenever relevant — \
+      check what exists before asking about it. Never promise to look at something later: \
+      you cannot act between replies, so look NOW, within this turn, then answer." if card.board.local_path.present?}
+    PROMPT
+  end
+  def conversation_turns(card)
+    card.events.where(kind: %w[user_message assistant_message]).last(30).map do |event|
+      "#{event.kind == "user_message" ? "User" : "You"}: #{event.text}"
+    end
+  end
+  def transcript_prompt(card)
+    <<~PROMPT
+      Conversation so far:
+      #{conversation_turns(card).join("\n\n")}
+      Reply to the user's latest message as the planning assistant. Output only your reply.
+    PROMPT
+  end
+end

data/app/jobs/mark_pr_ready_job.rb ADDED Viewed

@@ -0,0 +1,18 @@
+# Column rule action (§17): take the card's PR out of draft — used by QA-style
+# columns where the work should be formally reviewable on GitHub.
+class MarkPrReadyJob < ApplicationJob
+  queue_as :default
+  def perform(card_id)
+    card = Card.find(card_id)
+    return if card.pr_url.blank?
+    out, status = Open3.capture2e("gh", "pr", "ready", card.pr_url)
+    if status.success? || out.downcase.include?("already")
+      card.update!(pr_state: "ready")
+      card.log!("status_change", text: "PR marked ready for review (out of draft)")
+    else
+      card.log!("error", text: "Could not mark PR ready: #{out.truncate(200)}")
+    end
+  end
+end

data/app/jobs/merge_pr_job.rb ADDED Viewed

@@ -0,0 +1,27 @@
+# Done's entry rule (§12.4 decision): dragging to the terminal column is the
+# irreversible act — mark the PR ready, squash-merge it, delete the branch.
+class MergePrJob < ApplicationJob
+  queue_as :default
+  def perform(card_id)
+    card = Card.find(card_id)
+    return if card.pr_url.blank? || card.pr_state == "merged"
+    # Best-effort undraft — a QA column may already have done it, and gh
+    # errors on an already-ready PR; the merge step is the real gate.
+    Open3.capture2e("gh", "pr", "ready", card.pr_url)
+    run_step(card, ["gh", "pr", "merge", card.pr_url, "--squash", "--delete-branch"]) or return
+    card.update!(pr_state: "merged")
+    card.log!("status_change", text: "PR squash-merged and branch deleted — shipped 🎉")
+  end
+  private
+  def run_step(card, cmd)
+    out, status = Open3.capture2e(*cmd)
+    return true if status.success?
+    card.log!("error", text: "Merge step failed (#{cmd[0..2].join(" ")}): #{out.truncate(200)}")
+    false
+  end
+end

data/app/jobs/resume_run_job.rb ADDED Viewed

@@ -0,0 +1,30 @@
+class ResumeRunJob < ApplicationJob
+  queue_as :default
+  # Resumes honor the column's WIP limit like any other start (§8): if the
+  # column is full, the answer is recorded and the card rejoins the queue;
+  # Column#kick_queue fires the pending resume when a slot frees.
+  def perform(run_id, message, approve: false)
+    run = Run.find(run_id)
+    return unless run.needs_input?
+    card = run.card
+    if card.column.execution? && card.column.at_wip_limit?
+      pending = run.briefing["pending_resume"]
+      combined = [pending&.dig("message"), message].compact_blank.join("\n\n")
+      run.update!(briefing: run.briefing.merge(
+        "pending_resume" => { "message" => combined, "approve" => approve || pending&.dig("approve") || false }
+      ))
+      card.update!(status: "queued")
+      card.log!("status_change", run: run, text: "Answer recorded — waiting for a free agent slot")
+      return
+    end
+    if (pending = run.briefing["pending_resume"])
+      run.update!(briefing: run.briefing.except("pending_resume"))
+      message = [pending["message"], message].compact_blank.join("\n\n")
+      approve ||= pending["approve"]
+    end
+    Agent::Runner.resume(run, message, approve: approve)
+  end
+end

data/app/jobs/start_run_job.rb ADDED Viewed

@@ -0,0 +1,13 @@
+class StartRunJob < ApplicationJob
+  queue_as :default
+  def perform(card_id)
+    card = Card.find(card_id)
+    return unless card.queued? && card.column.execution?
+    return if card.column.at_wip_limit? # stays queued; kicked when a slot frees
+    session = card.agent_sessions.create!(status: "provisioning", model: card.column.model)
+    run = session.runs.create!(status: "queued", briefing: { "card" => card.title, "column" => card.column.name })
+    Agent::Runner.start(run)
+  end
+end

data/app/mailers/application_mailer.rb ADDED Viewed

@@ -0,0 +1,4 @@
+class ApplicationMailer < ActionMailer::Base
+  default from: "from@example.com"
+  layout "mailer"
+end

data/app/models/agent_session.rb ADDED Viewed

@@ -0,0 +1,8 @@
+class AgentSession < ApplicationRecord
+  STATUSES = %w[provisioning ready torn_down].freeze
+  belongs_to :card
+  has_many :runs, dependent: :destroy
+  enum :status, STATUSES.index_by(&:itself)
+end

data/app/models/application_record.rb ADDED Viewed

@@ -0,0 +1,3 @@
+class ApplicationRecord < ActiveRecord::Base
+  primary_abstract_class
+end

data/app/models/artifact.rb ADDED Viewed

@@ -0,0 +1,8 @@
+class Artifact < ApplicationRecord
+  KINDS = %w[pull_request file report link].freeze
+  belongs_to :run
+  validates :kind, inclusion: { in: KINDS }
+  validates :name, presence: true
+end

data/app/models/board.rb ADDED Viewed

@@ -0,0 +1,60 @@
+class Board < ApplicationRecord
+  DEFAULT_COLUMNS = [
+    { name: "Tasks",       archetype: "inbox",     policy: {} },
+    { name: "Planning",    archetype: "planning",  policy: { "model" => "claude-haiku-4-5-20251001" } },
+    { name: "In Progress", archetype: "execution",
+      policy: { "model" => "claude-sonnet-4-6", "effort" => "high", "concurrency_limit" => 3,
+                "plan_approval" => true, "max_turns" => 80, "timeout_minutes" => 30,
+                "on_entry" => [{ "action" => "start_agent_run" }] } },
+    { name: "Review",      archetype: "review",    policy: {} },
+    { name: "QA",          archetype: "review",
+      policy: { "on_entry" => [{ "action" => "mark_pr_ready" }],
+                "on_entry_text" => "Take the PR out of draft — mark it ready for review on GitHub." } },
+    { name: "Done",        archetype: "terminal",
+      policy: { "on_entry" => [{ "action" => "merge_pr" }], "arrivals" => "top" } }
+  ].freeze
+  has_many :columns, -> { order(:position) }, dependent: :destroy
+  has_many :cards, dependent: :destroy
+  validates :name, presence: true
+  # First-run setup for a portable instance (cardinal.md §16): build the board
+  # from the repo Cardinal was launched inside.
+  def self.bootstrap!(repo_path)
+    repo_path = File.expand_path(repo_path)
+    # Raw configured URL (get-url applies insteadOf rewrites, which can embed
+    # credential-helper tokens); strip any userinfo defensively either way.
+    origin, origin_ok = Open3.capture2e("git", "-C", repo_path, "config", "--get", "remote.origin.url")
+    branch, branch_ok = Open3.capture2e("git", "-C", repo_path, "rev-parse", "--abbrev-ref", "HEAD")
+    board = create!(
+      name: File.basename(repo_path),
+      repo_url: origin_ok.success? ? sanitize_remote_url(origin.strip) : nil,
+      default_branch: branch_ok.success? && branch.strip.present? ? branch.strip : "main",
+      local_path: repo_path
+    )
+    DEFAULT_COLUMNS.each_with_index do |attrs, index|
+      board.columns.create!(position: index, **attrs)
+    end
+    board
+  end
+  def self.sanitize_remote_url(url)
+    # Drop any userinfo (tokens from credential-helper rewrites). Regex, not
+    # URI#userinfo= — Ruby 3.4's RFC3986 parser silently ignores that setter.
+    url.sub(%r{\A(\w+://)[^@/]+@}, '\1')
+  end
+  # Every tag in use on this board — the pool the tag picker offers.
+  def tag_pool
+    cards.pluck(:tags).flatten.compact.uniq.sort
+  end
+  # Cards currently waiting on the human, ordered by urgency — feeds the
+  # attention inbox in the board header.
+  def attention_cards
+    cards.where(status: %w[needs_input failed work_complete])
+         .order(Arel.sql("CASE status WHEN 'needs_input' THEN 0 WHEN 'failed' THEN 1 ELSE 2 END"), updated_at: :asc)
+  end
+end

data/app/models/card.rb ADDED Viewed

@@ -0,0 +1,83 @@
+class Card < ApplicationRecord
+  STATUSES = %w[
+    draft discussing queued working needs_input blocked failed
+    work_complete in_review changes_requested approved done archived
+  ].freeze
+  # Which statuses a card may hold while sitting in each column archetype.
+  # The column move is the trigger; this map keeps the state machine honest (§3).
+  LEGAL_STATUSES = {
+    "inbox"     => %w[draft archived],
+    "planning"  => %w[draft discussing archived],
+    "execution" => %w[queued working needs_input blocked failed work_complete archived],
+    "review"    => %w[in_review changes_requested approved archived],
+    "terminal"  => %w[done archived]
+  }.freeze
+  belongs_to :board
+  belongs_to :column
+  belongs_to :parent, class_name: "Card", optional: true
+  has_many :children, class_name: "Card", foreign_key: :parent_id,
+                      dependent: :nullify, inverse_of: :parent
+  has_many :events, -> { order(:created_at, :id) }, dependent: :destroy
+  has_many :agent_sessions, dependent: :destroy
+  has_many :runs, through: :agent_sessions
+  enum :status, STATUSES.index_by(&:itself)
+  validates :title, presence: true
+  validate :status_legal_for_column
+  before_validation :assign_number_and_position, on: :create
+  after_commit -> { broadcast_refresh_to board }
+  scope :attention, -> { where(status: %w[needs_input blocked failed work_complete]) }
+  def needs_attention? = %w[needs_input blocked failed work_complete].include?(status)
+  def running? = %w[queued working needs_input].include?(status)
+  # Latest one-line progress event, shown live on the card face (§6).
+  def latest_progress
+    events.where(kind: "progress").last&.payload&.[]("text")
+  end
+  # Is the planning assistant expected to post next? True right after entering
+  # a planning column (kickoff inspection pending) or after a user message.
+  def awaiting_assistant?
+    return false unless column.planning?
+    last = events.where(kind: %w[user_message assistant_message error column_move]).order(:id).last
+    last.present? && %w[user_message column_move].include?(last.kind)
+  end
+  # Some AI is expected to write to this card imminently.
+  def thinking?
+    awaiting_assistant? || working?
+  end
+  # URLs speak card numbers, matching every other surface (header #N,
+  # branches, PR titles) — not database ids, which drift after deletions.
+  def to_param = number.to_s
+  def default_branch_name
+    "cardinal/#{number}-#{title.parameterize[0, 40]}"
+  end
+  def log!(kind, actor: "system", run: nil, **payload)
+    events.create!(kind:, actor:, run:, payload:)
+  end
+  private
+  def assign_number_and_position
+    self.number ||= (board.cards.maximum(:number) || 0) + 1
+    self.position ||= (column.cards.maximum(:position) || -1) + 1
+  end
+  def status_legal_for_column
+    return if column.blank? || status.blank?
+    legal = LEGAL_STATUSES.fetch(column.archetype, STATUSES)
+    errors.add(:status, "#{status} is not legal in a #{column.archetype} column") unless legal.include?(status)
+  end
+end

data/app/models/column.rb ADDED Viewed

@@ -0,0 +1,83 @@
+class Column < ApplicationRecord
+  ARCHETYPES = %w[inbox planning execution review terminal].freeze
+  belongs_to :board
+  has_many :cards, -> { order(:position) }, dependent: :restrict_with_error
+  enum :archetype, ARCHETYPES.index_by(&:itself)
+  # The policy blob is the column's entire behavior configuration (§1, §14.3).
+  store_accessor :policy, :instructions, :model, :effort, :concurrency_limit,
+                 :plan_approval, :budget_per_run_cents, :timeout_minutes,
+                 :max_turns, :tools, :on_entry, :on_success, :color, :arrivals,
+                 :accepts_from
+  # Only ever emit a validated hex color into inline styles.
+  def safe_color
+    color if color.to_s.match?(/\A#\h{6}\z/)
+  end
+  # Which columns may move cards INTO this one (§ accept policy, card #15).
+  # Stored as an array of column-id strings; blank = accept from anywhere, so
+  # existing boards keep their unrestricted behavior.
+  def accepts?(source_column)
+    ids = Array(accepts_from).map(&:to_s).reject(&:blank?)
+    ids.empty? || ids.include?(source_column.id.to_s)
+  end
+  # Start the next queued card when a run slot frees up. A queued card whose
+  # run parked and already has its answer recorded resumes instead of
+  # starting fresh.
+  def kick_queue
+    return if at_wip_limit?
+    next_card = cards.where(status: "queued").order(:position).first
+    return unless next_card
+    parked = next_card.runs.where(status: "needs_input").order(:id).last
+    if parked&.briefing&.key?("pending_resume")
+      ResumeRunJob.perform_later(parked.id, "")
+    else
+      StartRunJob.perform_later(next_card.id)
+    end
+  end
+  # "claude-sonnet-4-6" → "sonnet", for compact chips on card faces.
+  def model_short
+    model.to_s[/claude-([a-z]+)/, 1] || model
+  end
+  validates :name, presence: true
+  validates :position, presence: true
+  def running_count = cards.where(status: "working").count
+  def queued_count  = cards.where(status: "queued").count
+  def at_wip_limit?
+    execution? && concurrency_limit.present? && running_count >= concurrency_limit.to_i
+  end
+  # The built-in role contract for AI servicing this archetype — shown
+  # read-only in the gear modal so the Instructions field is understood as
+  # ADDING to this, never replacing it. Enforced in code, not editable.
+  BUILT_IN_ROLES = {
+    "planning"  => "Plans only, never implements: read-only tools (physically cannot change files), " \
+                   "drives toward a Ready-for-execution brief, and hands off — approval means " \
+                   "\"finalize the brief\", not \"do it\".",
+    "execution" => "Full toolset in an isolated checkout of the card's branch. Commits as it goes but " \
+                   "never pushes (the runner pushes); merges the default branch itself on conflict; " \
+                   "parks with a QUESTION: when genuinely blocked; ends with a final report."
+  }.freeze
+  def built_in_role = BUILT_IN_ROLES[archetype]
+  # One-line consequence shown while dragging a card over this column (§14.1).
+  def drag_hint
+    case archetype
+    when "inbox"     then "Parked — no agent activity"
+    when "planning"  then "The board assistant will join the discussion"
+    when "execution" then "An agent will be assigned and start work"
+    when "review"    then "Work stops — ready for your verdict"
+    when "terminal"  then "Ships it — PR merged, branch deleted"
+    end
+  end
+end

data/app/models/event.rb ADDED Viewed

@@ -0,0 +1,44 @@
+class Event < ApplicationRecord
+  KINDS = %w[
+    user_message agent_message assistant_message
+    status_change column_move move_rejected plan_proposed plan_approved
+    question answer progress
+    tool_call tool_result artifact_created
+    run_started run_finished final_report error
+  ].freeze
+  # Which timeline zoom level an event first appears at (§7).
+  CONVERSATION_KINDS = %w[user_message agent_message assistant_message question answer
+                          plan_proposed plan_approved final_report error
+                          column_move move_rejected].freeze
+  belongs_to :card
+  belongs_to :run, optional: true
+  validates :kind, inclusion: { in: KINDS }
+  validates :actor, presence: true
+  scope :conversation, -> { where(kind: CONVERSATION_KINDS) }
+  scope :activity, -> { where.not(kind: %w[tool_call tool_result]) }
+  # Live-append new events into any open card modal. User-authored events are
+  # skipped — they arrive via the form's own redirect re-render.
+  after_create_commit -> {
+    broadcast_append_to card, target: "card_events", partial: "events/event", locals: { event: self }
+  }, unless: -> { actor == "user" }
+  # These kinds mean the AI has delivered what the typing indicator promised.
+  RESOLVES_THINKING = %w[assistant_message final_report question plan_proposed error].freeze
+  # Kinds that change what a card FACE shows (progress lines, thinking chip,
+  # replied chip) — the board must morph on these, not just the open modal.
+  REFRESHES_BOARD = (%w[progress run_started run_finished] + RESOLVES_THINKING).freeze
+  after_create_commit -> { card.broadcast_refresh_to card.board },
+                      if: -> { REFRESHES_BOARD.include?(kind) }
+  after_create_commit -> { broadcast_remove_to card, target: "typing-indicator" },
+                      if: -> { RESOLVES_THINKING.include?(kind) }
+  def text = payload["text"]
+end