cardinal-ai 0.0.1 → 0.2.3

data/app/services/claude_cli.rb

@@ -0,0 +1,89 @@
+# The single auth path for all of Cardinal's AI (§17): every tier — planning
+# assistant, maintenance agents, rules compiler, worker agents — goes through
+# the claude CLI, so wherever Claude Code is logged in (or an API key is
+# exported), Cardinal works. No separate key provisioning.
+#
+# This module covers the one-shot tiers; worker agents have their own
+# streaming path in Agent::Runner.
+module ClaudeCli
+  class Error < StandardError
+    # Human message in #message; raw technical payload in #detail (shown only
+    # behind a disclosure in the timeline).
+    attr_reader :detail
+
+    def initialize(message, detail: nil)
+      super(message)
+      @detail = detail
+    end
+  end
+
+  # Nested-session guards + creds the model never needs. A blank
+  # ANTHROPIC_API_KEY is removed too (it would shadow CLI session auth).
+  STRIP_ENV = %w[CLAUDECODE CLAUDE_CODE_ENTRYPOINT GH_TOKEN GITHUB_TOKEN].freeze
+
+  WRAP_UP = "You have hit your exploration limit. Using only what you have already " \
+            "learned, give your best complete reply now. Do not use any tools.".freeze
+
+  def self.available?
+    return @available if defined?(@available)
+    @available = system("which claude > /dev/null 2>&1")
+  end
+
+  # tools: comma-separated read-only tool list (e.g. "Read,Glob,Grep") with
+  # cwd pointing at the repo. Default remains tool-less single-turn.
+  # resume: continue an existing claude session (context carries over).
+  # with_session: return [text, session_id] instead of just text, so callers
+  # can keep a continuing conversation (the planning assistant does).
+  def self.prompt(text, system: nil, model: nil, tools: nil, cwd: nil, max_turns: 1,
+                  resume: nil, with_session: false)
+    raise Error.new("claude CLI not found on PATH") unless available?
+
+    json = invoke(text, system:, model:, tools:, cwd:, max_turns:, resume:)
+    if success?(json)
+      return with_session ? [json["result"].to_s, json["session_id"]] : json["result"].to_s
+    end
+
+    # Ran out of turns mid-exploration: resume the same session tool-less and
+    # force an answer from the context it already gathered.
+    if json["subtype"] == "error_max_turns" && json["session_id"].present?
+      wrapped = invoke(WRAP_UP, model:, cwd:, tools: "", max_turns: 2, resume: json["session_id"])
+      if success?(wrapped)
+        return with_session ? [wrapped["result"].to_s, wrapped["session_id"] || json["session_id"]] : wrapped["result"].to_s
+      end
+      raise Error.new("ran out of working turns and couldn't wrap up — try again, or simplify the ask",
+                      detail: wrapped.to_json)
+    end
+
+    raise Error.new(friendly_failure(json), detail: json.to_json)
+  end
+
+  def self.success?(json)
+    json["subtype"] == "success" && !json["is_error"]
+  end
+
+  def self.friendly_failure(json)
+    case json["subtype"]
+    when "error_max_turns"        then "ran out of working turns before finishing"
+    when "error_during_execution" then "hit an internal error while working"
+    else "failed (#{json["subtype"].presence || "unknown error"})"
+    end
+  end
+
+  def self.invoke(text, system: nil, model: nil, tools: nil, cwd: nil, max_turns: 1, resume: nil)
+    cmd = ["claude", "-p", text, "--output-format", "json",
+           "--max-turns", max_turns.to_s, "--tools", tools.presence || ""]
+    cmd += ["--append-system-prompt", system] if system.present?
+    cmd += ["--model", model] if model.present?
+    cmd += ["--resume", resume] if resume.present?
+
+    env = STRIP_ENV.index_with { nil }
+    env["ANTHROPIC_API_KEY"] = nil if ENV["ANTHROPIC_API_KEY"].blank?
+
+    spawn_opts = cwd.present? && Dir.exist?(cwd) ? { chdir: cwd } : {}
+    out, err, status = Open3.capture3(env, *cmd, **spawn_opts)
+    JSON.parse(out)
+  rescue JSON::ParserError
+    raise Error.new("claude produced no readable result (exit #{status&.exitstatus || "?"})",
+                    detail: [err, out].compact_blank.join("\n---\n").truncate(1500))
+  end
+end

data/app/services/rules/compiler.rb

@@ -0,0 +1,55 @@
+module Rules
+  # Turns a plain-English description of a column's on-entry behavior into the
+  # rule actions the dispatcher executes (§17). English is the source of
+  # truth; the compiled JSON is stored alongside it and shown read-only.
+  module Compiler
+    Error = Class.new(StandardError)
+
+    VOCABULARY = <<~DOC.freeze
+      Available actions:
+      - {"action": "assistant_greeting"} — the planning assistant posts an opening message
+      - {"action": "start_agent_run"} — assign a dedicated worker agent to the card and start a run
+      - {"action": "ai_task", "prompt": "...", "model": "optional-model-id"} — a one-shot AI maintenance
+        task; the prompt may use %{title}, %{description}, %{conversation}; its output is posted to the
+        card timeline
+      - {"action": "mark_pr_ready"} — take the card's PR out of draft (ready for review on GitHub)
+      - {"action": "merge_pr"} — mark the card's PR ready, squash-merge it, delete the branch
+      - {"action": "set_status", "status": "..."} — force a card status
+    DOC
+
+    def self.compile(text)
+      raise Error, "Rules compiler needs the claude CLI — use the advanced JSON editor instead." unless ClaudeCli.available?
+
+      raw = ClaudeCli.prompt(
+        text,
+        model: AssistantReplyJob::FALLBACK_MODEL,
+        system: <<~SYS
+          You compile plain-English descriptions of Kanban column automation into JSON rule
+          arrays for the Cardinal board engine.
+
+          #{VOCABULARY}
+          Respond with ONLY the JSON array — no prose, no code fences. If the description
+          asks for something outside the vocabulary, approximate it with an ai_task whose
+          prompt captures the intent.
+        SYS
+      ).strip
+      raw = raw.sub(/\A```(?:json)?\s*/, "").sub(/```\z/, "").strip
+      rules = JSON.parse(raw)
+      validate!(rules)
+      rules
+    rescue JSON::ParserError
+      raise Error, "Compiler returned invalid JSON — try rephrasing, or use the advanced editor."
+    rescue ClaudeCli::Error => e
+      raise Error, "Compiler call failed: #{e.message.truncate(120)}"
+    end
+
+    def self.validate!(rules)
+      raise Error, "Expected a JSON array of rules" unless rules.is_a?(Array)
+      known = %w[assistant_greeting start_agent_run ai_task mark_pr_ready merge_pr set_status]
+      rules.each do |rule|
+        raise Error, "Each rule must be an object with an \"action\"" unless rule.is_a?(Hash) && rule["action"].present?
+        raise Error, "Unknown action #{rule["action"].inspect}" unless known.include?(rule["action"])
+      end
+    end
+  end
+end

data/app/services/rules.rb

@@ -0,0 +1,67 @@
+# Column rules (cardinal.md §17): a column's on_entry policy is a list of rule
+# actions fired when a card lands in it. Archetypes only supply defaults —
+# any column can carry any rules, including one-shot AI maintenance tasks.
+module Rules
+  DEFAULTS = {
+    "planning"  => [{ "action" => "assistant_greeting" }],
+    "execution" => [{ "action" => "start_agent_run" }],
+    "terminal"  => [{ "action" => "merge_pr" }]
+  }.freeze
+
+  # Shown in the gear modal so the archetype's built-in behavior is visible,
+  # not implied (the on-entry box being blank doesn't mean nothing happens).
+  DEFAULT_DESCRIPTIONS = {
+    "inbox"     => "Nothing — cards park here untouched.",
+    "planning"  => "The planning assistant inspects the card and opens the conversation: it reads the title and description, then asks its sharpest clarifying questions to improve the card before execution. Tune its focus with the Instructions field above.",
+    "execution" => "A dedicated worker agent is assigned to the card and a run starts (plan-first if plan approval is on).",
+    "review"    => "Nothing automatic — the card waits for your verdict.",
+    "terminal"  => "The card's PR is marked ready, squash-merged, and its branch deleted."
+  }.freeze
+
+  def self.fire_entry(card, column)
+    each_rule(column.policy["on_entry"], column.archetype) do |rule|
+      apply(rule, card, column)
+    end
+  end
+
+  def self.each_rule(configured, archetype, &block)
+    rules = configured.presence || DEFAULTS[archetype] || []
+    rules = [rules] if rules.is_a?(Hash) || rules.is_a?(String)
+    rules.map { |r| r.is_a?(String) ? { "action" => r } : r }.each(&block)
+  end
+
+  def self.apply(rule, card, column)
+    case rule["action"]
+    when "assistant_greeting"
+      # Contextual opener: the assistant reads the card and asks targeted
+      # questions (AssistantReplyJob falls back to a canned line without a key).
+      AssistantReplyJob.perform_later(card, kickoff: true)
+    when "start_agent_run"
+      card.update!(branch_name: card.branch_name.presence || card.default_branch_name)
+      card.log!("status_change", text: "Queued for execution on #{card.branch_name}")
+      StartRunJob.perform_later(card.id)
+    when "ai_task"
+      # One-shot maintenance agent: a bounded Messages API call whose prompt
+      # comes from the rule config. No workspace, no session, no tools.
+      AiTaskJob.perform_later(card.id, rule["prompt"].to_s, rule["model"])
+    when "mark_pr_ready"
+      if card.pr_url.present?
+        card.log!("status_change", text: "Taking the PR out of draft…")
+        MarkPrReadyJob.perform_later(card.id)
+      else
+        card.log!("status_change", text: "No PR to mark ready")
+      end
+    when "merge_pr"
+      if card.pr_url.present?
+        card.log!("status_change", text: "Shipping: merging #{card.pr_url}")
+        MergePrJob.perform_later(card.id)
+      else
+        card.log!("status_change", text: "Card finalized (no PR to merge)")
+      end
+    when "set_status"
+      card.update!(status: rule["status"]) if Card::STATUSES.include?(rule["status"])
+    else
+      card.log!("error", text: "Unknown column rule: #{rule["action"].inspect}")
+    end
+  end
+end

data/app/services/run_sweeper.rb

@@ -0,0 +1,52 @@
+# Reliability layer (cardinal.md §11): no run may stay "running" without a
+# live process behind it. The server boots a sweeper thread (see
+# config/initializers/run_sweeper.rb) that fails silent runs and unsticks
+# their cards, then re-kicks execution queues.
+module RunSweeper
+  HEARTBEAT_GRACE = 3.minutes
+
+  def self.sweep
+    fail_dead_runs
+    repair_stuck_cards
+    kick_queues
+  end
+
+  def self.fail_dead_runs
+    Run.where(status: %w[queued running]).find_each do |run|
+      next if alive?(run)
+      next if run.heartbeat_at && run.heartbeat_at > HEARTBEAT_GRACE.ago
+      next if run.heartbeat_at.nil? && run.created_at > HEARTBEAT_GRACE.ago
+
+      run.update!(status: "failed", finished_at: Time.current,
+                  result_summary: "Runner died without finishing (swept)")
+      card = run.card
+      if card.working? || card.queued?
+        card.update!(status: "failed")
+        card.log!("error", run: run, text: "Run ##{run.id} lost its runner process and was marked failed. Retry by dragging the card out and back into the column.")
+      end
+    end
+  end
+
+  # Cards left "working" with no live or recorded run — e.g. a crash between
+  # state writes.
+  def self.repair_stuck_cards
+    Card.where(status: "working").find_each do |card|
+      next if card.runs.where(status: %w[queued running needs_input]).any? { |r| r.needs_input? || alive?(r) }
+      card.update!(status: "failed")
+      card.log!("error", text: "Card was stuck working with no live run; marked failed.")
+    end
+  end
+
+  def self.kick_queues
+    Column.where(archetype: "execution").find_each(&:kick_queue)
+  end
+
+  def self.alive?(run)
+    pid = run.agent_session&.config&.dig("pid")
+    return false if pid.blank?
+    Process.kill(0, Integer(pid))
+    true
+  rescue Errno::ESRCH, Errno::EPERM, ArgumentError
+    false
+  end
+end

data/app/views/boards/show.html.erb

@@ -0,0 +1,79 @@
+<%= turbo_stream_from @board %>
+
+<header class="topbar">
+  <h1>Cardinal AI <span class="sep">▸</span> <%= @board.name %></h1>
+  <div class="topbar-right">
+    <button type="button" class="theme-toggle"
+            data-controller="theme" data-action="theme#toggle">☀ Light</button>
+    <% if ENV["CARDINAL_AUTH"].present? %>
+      <span class="auth-chip" title="<%= ENV["CARDINAL_AUTH"] == "dedicated" ? "This board runs as its own linked Claude account (.cardinal/claude). Switch with: cardinal login" : "This board inherits the machine's claude login (CARDINAL_INHERIT_AUTH=1)" %>">
+        🔐 <%= ENV["CARDINAL_AUTH"] == "dedicated" ? "board account" : "machine account" %>
+      </span>
+    <% end %>
+    <% attention = @board.attention_cards %>
+    <% working = @board.cards.where(status: "working").order(:updated_at) %>
+    <% queued = @board.cards.where(status: "queued").order(:position) %>
+    <% if attention.any? || working.any? || queued.any? %>
+      <details class="attention">
+        <summary>
+          <% if attention.any? %><span class="attn-part">⚠ <%= attention.size %> need you</span><% end %>
+          <% if working.any? %><span class="attn-part working-part"><span class="pulse-dot"></span> <%= working.size %> working</span><% end %>
+          <% if queued.any? %><span class="attn-part">⏳ <%= queued.size %> queued</span><% end %>
+        </summary>
+        <div class="attention-list">
+          <% if attention.any? %>
+            <p class="attn-header">Needs you</p>
+            <ul>
+              <% attention.each do |card| %>
+                <li><%= link_to "##{card.number} #{card.title} — #{card.status.humanize.downcase}",
+                                card_path(card), data: { turbo_frame: "modal", turbo_action: "advance" } %></li>
+              <% end %>
+            </ul>
+          <% end %>
+          <% if working.any? %>
+            <p class="attn-header">Working</p>
+            <ul>
+              <% working.each do |card| %>
+                <li class="attn-working">
+                  <span class="pulse-dot"></span>
+                  <%= link_to card_path(card), data: { turbo_frame: "modal", turbo_action: "advance" } do %>
+                    #<%= card.number %> <%= card.title %><span class="hint"> — <%= card.latest_progress&.truncate(60) || "starting…" %></span>
+                  <% end %>
+                </li>
+              <% end %>
+            </ul>
+          <% end %>
+          <% if queued.any? %>
+            <p class="attn-header">Queued</p>
+            <ul>
+              <% queued.each_with_index do |card, index| %>
+                <li><%= link_to "##{card.number} #{card.title} — #{index.zero? ? "next up" : "#{index} ahead"}",
+                                card_path(card), data: { turbo_frame: "modal", turbo_action: "advance" } %></li>
+              <% end %>
+            </ul>
+          <% end %>
+        </div>
+      </details>
+    <% end %>
+    <details class="new-column">
+      <summary>+ Column</summary>
+      <%= form_with url: columns_path, class: "new-column-form" do |f| %>
+        <%= f.text_field "column[name]", placeholder: "Column name", required: true %>
+<%# Inbox is the board's single intake — it can't be created a second time (card #17). %>
+        <%= f.select "column[archetype]",
+              (Column::ARCHETYPES - %w[inbox]).map { |a| [a.capitalize, a] }, selected: "planning" %>
+        <%= f.submit "Add" %>
+      <% end %>
+    </details>
+  </div>
+</header>
+
+<main class="board">
+  <% @board.columns.each do |column| %>
+    <%= render "columns/column", column: column %>
+  <% end %>
+</main>
+
+<%= turbo_frame_tag "modal", data: { turbo_permanent: true } do %>
+  <%= render "cards/detail" if @card %>
+<% end %>

data/app/views/cards/_card.html.erb

@@ -0,0 +1,48 @@
+<article class="card status-<%= card.status %>" id="<%= dom_id(card) %>" data-card-id="<%= card.number %>">
+  <%= link_to card_path(card), class: "card-link", data: { turbo_frame: "modal", turbo_action: "advance" } do %>
+    <div class="card-title">
+      <%= card.title %>
+      <span class="status-glyph"><%= { "working" => "⚡", "needs_input" => "❓", "failed" => "✖",
+                                       "work_complete" => "✅", "done" => "✓", "queued" => "⏳",
+                                       "discussing" => "💬", "in_review" => "👁", "approved" => "👍",
+                                       "changes_requested" => "🔁" }[card.status] %></span>
+    </div>
+    <% if card.queued? %>
+      <% ahead = card.column.cards.where(status: "queued").where("position < ?", card.position).count %>
+      <p class="card-progress">⏳ queued<%= ahead.positive? ? " — #{ahead} ahead" : " — next up" %></p>
+    <% elsif card.working? %>
+      <p class="card-progress working-line"><span class="spinner"></span> <%= card.latest_progress || "agent starting…" %></p>
+    <% elsif card.latest_progress && card.running? %>
+      <p class="card-progress">▸ <%= card.latest_progress %></p>
+    <% elsif card.approved? %>
+      <p class="card-progress approved-text">👍 approved — drag to Done to ship</p>
+    <% elsif card.changes_requested? %>
+      <p class="card-progress attention-text">🔁 changes requested</p>
+    <% elsif card.needs_attention? %>
+      <p class="card-progress attention-text"><%= card.status.humanize %></p>
+    <% end %>
+    <div class="card-meta">
+      <% card.tags.each do |tag| %><span class="tag"><%= tag %></span><% end %>
+      <% if card.running? && card.column.model %>
+        <span class="chip agent-chip">🤖 <%= card.column.model_short %><%= " · #{card.column.effort}" if card.column.effort %></span>
+      <% end %>
+      <% if card.awaiting_assistant? %>
+        <span class="chip agent-chip thinking-chip">🪶 <span class="typing-dots mini"><span></span><span></span><span></span></span></span>
+      <% elsif card.discussing? && card.events.conversation.last&.actor == "assistant" %>
+        <span class="chip agent-chip">🪶 replied</span>
+      <% end %>
+      <% if (card.running? || card.needs_attention?) && (last_run = card.runs.order(:id).last) && (last_run.cost.to_f.positive? || last_run.output_tokens.positive?) %>
+        <span class="chip">$<%= last_run.cost.round(2) %><%= " · #{(last_run.output_tokens / 1000.0).round(1)}k out" if card.working? %></span>
+      <% end %>
+      <% if card.parent_id %><span class="chip">↑ sub</span><% end %>
+      <% if card.children.any? %><span class="chip">↳ <%= card.children.where(status: %w[done archived]).count %>/<%= card.children.count %></span><% end %>
+      <% if card.branch_name && card.pr_url.blank? %><span class="chip branch">🌿 <%= card.branch_name.delete_prefix("cardinal/") %></span><% end %>
+    </div>
+  <% end %>
+  <% if card.pr_url %>
+    <a class="card-footer" href="<%= card.pr_url %>" target="_blank" rel="noopener" title="Open the pull request on GitHub">
+      <span class="footer-left"><%# future: Asana / Trello / linked-ticket slot %></span>
+      <span class="footer-pr">GitHub #<%= card.pr_url[%r{/pull/(\d+)}, 1] %> ↗</span>
+    </a>
+  <% end %>
+</article>

data/app/views/cards/_detail.html.erb

@@ -0,0 +1,190 @@
+  <div class="modal-backdrop" data-controller="modal" data-action="click->modal#backdrop">
+    <div class="modal card-detail">
+      <%= turbo_stream_from @card %>
+      <header class="modal-header">
+        <h1>
+          <%= @card.title %>
+          <span class="chip status-chip status-<%= @card.status %>"><%= @card.status.humanize %></span>
+          <span class="card-number-sub" title="Card number — how branches, PRs, and other cards refer to this card">#<%= @card.number %></span>
+        </h1>
+        <div class="modal-header-right">
+          <% if @card.branch_name %>
+            <span class="git-line">
+              <span class="branch-base"><%= @card.board.default_branch %></span>
+              <span class="git-arrow">→</span>
+              <span class="branch-pill" data-controller="clipboard" data-clipboard-text-value="<%= @card.branch_name %>">
+                <code><%= @card.branch_name %></code>
+                <button type="button" class="copy-btn" data-clipboard-target="button"
+                        data-action="clipboard#copy" title="Copy branch name">⧉</button>
+              </span>
+              <% if @card.pr_url %>
+                <span class="git-arrow">→</span>
+                <%= link_to "##{@card.pr_url[%r{/pull/(\d+)}, 1]}", @card.pr_url, target: "_blank", rel: "noopener", class: "pr-link" %>
+                <% if @card.pr_state.present? %><span class="pr-state">(<%= @card.pr_state %>)</span><% end %>
+              <% end %>
+            </span>
+          <% end %>
+          <button type="button" class="modal-close" data-action="modal#close" title="Close (Esc)">✕</button>
+        </div>
+      </header>
+
+      <div class="detail-panes">
+        <section class="timeline" data-controller="scroll">
+          <nav class="zoom-tabs">
+            <% %w[conversation activity debug].each do |zoom| %>
+              <%= link_to zoom.capitalize, card_path(@card, zoom: zoom),
+                          class: ("active" if @zoom == zoom) %>
+            <% end %>
+          </nav>
+
+          <div class="timeline-scroll" data-scroll-target="scroller">
+            <% if @card.description.present? %>
+              <div class="event event-description"><%= render_markdown @card.description %></div>
+            <% end %>
+
+            <div id="card_events">
+              <%= render partial: "events/event", collection: @events %>
+              <% if @events.empty? %>
+                <p class="empty">No events yet — this card hasn't been anywhere.</p>
+              <% end %>
+            </div>
+
+            <% if @card.thinking? %>
+              <div class="event typing" id="typing-indicator">
+                <span class="event-actor"><%= @card.working? ? "🤖" : "🪶" %></span>
+                <div class="typing-dots"><span></span><span></span><span></span></div>
+              </div>
+            <% end %>
+          </div>
+
+          <button type="button" class="new-messages-pill" data-scroll-target="pill"
+                  data-action="scroll#jump">↓ New messages</button>
+
+          <%= form_with url: card_messages_path(@card), class: "message-form" do |f| %>
+            <%= f.text_area "message[text]", rows: 2, required: true,
+                  data: { controller: "composer", action: "keydown->composer#keydown" },
+                  placeholder: (@card.column.planning? ? "Discuss this card with the planning assistant…" : "Add a note to this card…") + " (Enter sends, Shift+Enter for a new line)" %>
+          <% end %>
+        </section>
+
+        <aside class="work-panel">
+          <div data-controller="autosave">
+            <h3>Details <span class="autosave-status" data-autosave-target="status"></span></h3>
+            <%= form_with model: @card, class: "card-edit",
+                  data: { autosave_target: "form", action: "input->autosave#save change->autosave#save" } do |f| %>
+              <%= hidden_field_tag :autosave, "1" %>
+              <label>Title</label>
+              <%= f.text_field :title, required: true %>
+              <label>Tags</label>
+              <%= render "cards/tag_picker", board: @card.board, tags: @card.tags %>
+              <label>Description</label>
+              <%= f.text_area :description, rows: 6 %>
+              <label>Branch <span class="hint">— optional</span></label>
+              <% if @card.branch_name.present? %>
+                <%# Locked once set — by the user here or by the agent on run start. %>
+                <p class="locked-field"><code><%= @card.branch_name %></code> <span class="hint">set</span></p>
+              <% else %>
+                <%= f.text_field :branch_name, placeholder: @card.default_branch_name %>
+              <% end %>
+              <label>Pull request <span class="hint">— optional</span></label>
+              <% if @card.pr_url.present? %>
+                <p class="locked-field"><%= link_to @card.pr_url, @card.pr_url, target: "_blank", rel: "noopener" %> <span class="hint">set</span></p>
+              <% else %>
+                <%= f.text_field :pr_url, placeholder: "https://github.com/owner/repo/pull/123" %>
+              <% end %>
+            <% end %>
+          </div>
+
+          <% if @card.parent || @card.children.any? %>
+            <h3>Related</h3>
+            <ul class="related-list">
+              <% if @card.parent %>
+                <li>↑ <%= link_to @card.parent.title, card_path(@card.parent), data: { turbo_frame: "modal", turbo_action: "advance" } %>
+                    <span class="hint"><%= @card.parent.status.humanize.downcase %></span></li>
+              <% end %>
+              <% @card.children.each do |child| %>
+                <li>↳ <%= link_to child.title, card_path(child), data: { turbo_frame: "modal", turbo_action: "advance" } %>
+                    <span class="hint"><%= child.status.humanize.downcase %></span></li>
+              <% end %>
+            </ul>
+          <% end %>
+          <%= link_to "+ Child card", new_card_path(parent_id: @card.id),
+                class: "child-card-link", data: { turbo_frame: "modal" } %>
+
+          <% if @card.column.review? %>
+            <h3>Review</h3>
+            <% if @card.pr_url %>
+              <%= link_to "View Pull Request", @card.pr_url, target: "_blank", rel: "noopener", class: "pr-view-btn" %>
+            <% end %>
+            <% if @card.in_review? %>
+              <div class="panel-callout callout-plan">
+                <p><strong>Your verdict.</strong> Check the final report in the timeline.
+                Approve, or just say what's wrong in the conversation — that marks it changes-requested,
+                and dragging the card back to a work column carries your feedback into the next run.</p>
+                <%= button_to "✅ Approve", approve_card_path(@card), class: "approve-btn", form_class: "align-right" %>
+              </div>
+            <% elsif @card.approved? %>
+              <div class="panel-callout callout-plan"><p><strong>Approved.</strong> Drag the card to Done to merge and ship.</p></div>
+            <% elsif @card.changes_requested? %>
+              <div class="panel-callout callout-question"><p><strong>Changes requested.</strong> Drag the card back to an execution column for a revision run — your conversation feedback rides along.</p></div>
+            <% end %>
+          <% end %>
+
+          <h3>Work</h3>
+          <% runs = @card.runs.order(:id) %>
+          <% parked = runs.select(&:needs_input?).last %>
+          <% latest = runs.last %>
+          <% if parked&.phase == "plan" %>
+            <div class="panel-callout callout-plan">
+              <p><strong>Plan proposed.</strong> Approve to let the agent execute, or reply in the timeline to redirect.</p>
+              <%= button_to "👍 Approve plan", approve_run_path(parked), class: "approve-btn", form_class: "align-right" %>
+            </div>
+          <% elsif parked&.restartable? %>
+            <div class="panel-callout callout-restart">
+              <p><strong>Run hit its turn budget.</strong> Restart to continue with a fresh budget, or raise <strong>Max turns</strong> in the column's gear settings.</p>
+              <%= button_to "🔄 Restart run", restart_run_path(parked), class: "restart-btn", form_class: "align-right" %>
+            </div>
+          <% elsif parked %>
+            <div class="panel-callout callout-question">
+              <p><strong>The agent has a question</strong> — answer it in the timeline message box.</p>
+            </div>
+          <% elsif latest&.failed? && latest.restartable? %>
+            <div class="panel-callout callout-restart">
+              <p><strong>Run failed on its budget.</strong> Restart to try again with a fresh budget, or raise the column's <strong>Max turns</strong> / timeout in its gear settings.</p>
+              <%= button_to "🔄 Restart run", restart_run_path(latest), class: "restart-btn", form_class: "align-right" %>
+            </div>
+          <% end %>
+          <% if runs.any? %>
+            <ul class="run-list">
+              <% runs.each do |run| %>
+                <li class="run run-<%= run.status %>">
+                  <span>Run #<%= run.id %> — <%= run.status %><%= " (#{run.phase})" if run.needs_input? %></span>
+                  <% if run.cost.positive? %>
+                    <span class="hint"><%= run.output_tokens %> out · $<%= run.cost.round(2) %></span>
+                  <% end %>
+                  <% if run.running? || run.needs_input? %>
+                    <%= button_to "✖ Cancel", cancel_run_path(run), class: "cancel-btn" %>
+                  <% end %>
+                </li>
+              <% end %>
+            </ul>
+            <% if @card.pr_url %>
+              <p>🌿 <%= link_to "View pull request", @card.pr_url, target: "_blank" %><%= " (#{@card.pr_state})" if @card.pr_state.present? %></p>
+            <% end %>
+          <% else %>
+            <p class="empty">No runs yet — drag the card into an execution column to assign an agent.</p>
+          <% end %>
+
+          <details class="advanced-rules panel-advanced">
+            <summary>Advanced</summary>
+            <p class="hint">Deleting removes the card and its entire history (events, runs, workspace). The remote branch and PR, if any, are left untouched.</p>
+            <%= button_to "🗑 Delete card", card_path(@card), method: :delete,
+                  class: "cancel-btn delete-card",
+                  form: { data: { turbo_frame: "_top", action: "turbo:submit-end->modal#closeOnSuccess",
+                                  turbo_confirm: "Delete ##{@card.number} \"#{@card.title}\" and its entire history? This cannot be undone." } },
+                  disabled: @card.working? %>
+          </details>
+        </aside>
+      </div>
+    </div>
+  </div>

data/app/views/cards/_tag_picker.html.erb

@@ -0,0 +1,12 @@
+<%# locals: board, tags (currently selected) %>
+<div data-controller="tags">
+  <%= hidden_field_tag "card[tags]", tags.join(", "), data: { tags_target: "field" } %>
+  <div class="tag-chips" data-tags-target="chips">
+    <% (board.tag_pool | tags).each do |tag| %>
+      <button type="button" class="tag-chip <%= "on" if tags.include?(tag) %>"
+              data-tag="<%= tag %>" data-action="tags#toggle"><%= tag %></button>
+    <% end %>
+  </div>
+  <input type="text" class="new-tag-input" placeholder="+ new tag (Enter)"
+         data-tags-target="newTag" data-action="keydown->tags#keydown">
+</div>

data/app/views/cards/new.html.erb

@@ -0,0 +1,35 @@
+<%= turbo_frame_tag "modal", data: { turbo_permanent: true } do %>
+  <div class="modal-backdrop" data-controller="modal" data-modal-sticky-value="true" data-action="click->modal#backdrop">
+    <div class="modal modal-sm">
+      <header class="modal-header">
+        <h1>New card<% if @parent %> <span class="hint">— child of “<%= @parent.title %>”</span><% end %></h1>
+        <button type="button" class="modal-close" data-action="modal#close" title="Cancel">✕</button>
+      </header>
+      <div class="modal-body">
+        <%# _top: a full-page redirect after create — Turbo suppresses this
+            tab's own refresh broadcast, so a frame-scoped response would
+            leave the board stale behind the modal. %>
+        <%= form_with url: cards_path, class: "card-edit",
+              data: { turbo_frame: "_top", action: "turbo:submit-end->modal#closeOnSuccess" } do |f| %>
+          <%= hidden_field_tag "card[parent_id]", @parent&.id %>
+          <label>Title</label>
+          <%= f.text_field "card[title]", required: true, autofocus: true, placeholder: "What needs doing?" %>
+          <label>Tags</label>
+          <%= render "cards/tag_picker", board: @board, tags: [] %>
+          <label>Description</label>
+          <%= f.text_area "card[description]", rows: 8,
+                placeholder: "Goal, context, acceptance criteria — the planning assistant will help refine this." %>
+          <label>Branch <span class="hint">— optional</span></label>
+          <%= f.text_field "card[branch_name]", placeholder: "cardinal/#{@board.cards.maximum(:number).to_i + 1}-feature-name" %>
+          <label>Pull request <span class="hint">— optional</span></label>
+          <%= f.text_field "card[pr_url]", placeholder: "https://github.com/owner/repo/pull/123" %>
+          <p class="hint">Leave blank and the agent picks a branch. Set either to point work at an existing branch or PR.</p>
+          <div class="card-edit-actions">
+            <button type="button" class="btn-cancel" data-action="modal#close">Cancel</button>
+            <%= f.submit "Save" %>
+          </div>
+        <% end %>
+      </div>
+    </div>
+  </div>
+<% end %>

data/app/views/cards/show.html.erb

@@ -0,0 +1,3 @@
+<%= turbo_frame_tag "modal", data: { turbo_permanent: true } do %>
+  <%= render "cards/detail" %>
+<% end %>