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

cardinal-ai 0.0.1 → 0.2.4

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 (108) 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 +530 -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 +130 -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 +43 -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 +45 -0
data/app/javascript/controllers/reveal_controller.js +15 -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 +92 -0
data/app/models/card.rb +83 -0
data/app/models/column.rb +134 -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 +92 -0
data/app/services/run_sweeper.rb +53 -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 +146 -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 +695 -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 +13 -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 +236 -9

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

@@ -0,0 +1,44 @@
+import { Controller } from "@hotwired/stimulus"
+// Chat-style timeline scrolling: pinned to the latest entry while you're at
+// (or near) the bottom; if you've scrolled up to read, new entries show a
+// "new messages" pill instead of yanking you down.
+export default class extends Controller {
+  static targets = ["scroller", "pill"]
+  NEAR = 90 // px from the bottom that still counts as "at the bottom"
+  connect() {
+    this.scrollToBottom()
+    this.observer = new MutationObserver(() => this.onAppend())
+    this.observer.observe(this.scrollerTarget, { childList: true, subtree: true })
+    this.onScroll = () => { if (this.nearBottom()) this.hidePill() }
+    this.scrollerTarget.addEventListener("scroll", this.onScroll)
+  }
+  disconnect() {
+    this.observer?.disconnect()
+    this.scrollerTarget?.removeEventListener("scroll", this.onScroll)
+  }
+  onAppend() {
+    this.nearBottom() ? this.scrollToBottom() : this.showPill()
+  }
+  jump() {
+    this.scrollToBottom()
+    this.hidePill()
+  }
+  nearBottom() {
+    const el = this.scrollerTarget
+    return el.scrollHeight - el.scrollTop - el.clientHeight < this.NEAR
+  }
+  scrollToBottom() {
+    this.scrollerTarget.scrollTop = this.scrollerTarget.scrollHeight
+  }
+  showPill() { this.pillTarget.classList.add("visible") }
+  hidePill() { this.pillTarget.classList.remove("visible") }
+}

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

@@ -0,0 +1,49 @@
+import { Controller } from "@hotwired/stimulus"
+// Tag picker: toggle existing tags, create new ones. Keeps a hidden
+// comma-joined field in sync and fires an input event so autosave notices.
+export default class extends Controller {
+  static targets = ["field", "chips", "newTag"]
+  toggle(event) {
+    event.preventDefault()
+    event.currentTarget.classList.toggle("on")
+    this.sync()
+  }
+  keydown(event) {
+    if (event.key !== "Enter") return
+    event.preventDefault()
+    this.add()
+  }
+  add() {
+    const name = this.newTagTarget.value.trim().toLowerCase()
+    this.newTagTarget.value = ""
+    if (name === "") return
+    const existing = this.chipTagged(name)
+    if (existing) {
+      existing.classList.add("on")
+    } else {
+      const chip = document.createElement("button")
+      chip.type = "button"
+      chip.className = "tag-chip on"
+      chip.dataset.tag = name
+      chip.dataset.action = "tags#toggle"
+      chip.textContent = name
+      this.chipsTarget.appendChild(chip)
+    }
+    this.sync()
+  }
+  chipTagged(name) {
+    return [...this.chipsTarget.querySelectorAll(".tag-chip")].find(c => c.dataset.tag === name)
+  }
+  sync() {
+    const selected = [...this.chipsTarget.querySelectorAll(".tag-chip.on")].map(c => c.dataset.tag)
+    this.fieldTarget.value = selected.join(", ")
+    this.fieldTarget.dispatchEvent(new Event("input", { bubbles: true }))
+  }
+}

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? && card.column.ai?
+    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,92 @@
+class Board < ApplicationRecord
+  # Captured from the author's live board (2026-07-05) — the battle-tested
+  # layout. accepts_from is stored as NAMES here and resolved to column ids
+  # by install_default_columns! (ids don't exist until creation).
+  DEFAULT_COLUMNS = [
+    { name: "Tasks",       archetype: "inbox",
+      policy: { "plan_approval" => false,
+                "accepts_from_names" => ["Planning", "Review", "QA", "Done"] } },
+    { name: "Planning",    archetype: "planning",
+      policy: { "ai" => true, "model" => "claude-haiku-4-5-20251001", "plan_approval" => false,
+                "on_entry" => [{ "action" => "assistant_greeting" }],
+                "on_entry_text" => "The planning assistant reads the card and opens the discussion.",
+                "accepts_from_names" => ["Tasks", "In Progress", "Review", "QA"] } },
+    { name: "In Progress", archetype: "execution",
+      policy: { "ai" => true, "model" => "claude-opus-4-8", "effort" => "high",
+                "concurrency_limit" => 3, "plan_approval" => true,
+                "budget_per_run_cents" => 200, "timeout_minutes" => 90, "max_turns" => 80,
+                "tools" => %w[read edit run_commands git_commit_push],
+                "on_entry" => [{ "action" => "start_agent_run" }],
+                "accepts_from_names" => ["Planning", "Review", "QA"],
+                "instructions" => "Follow repo conventions. Write tests when the repo has a suite." } },
+    { name: "Review",      archetype: "review",
+      policy: { "ai" => true, "plan_approval" => false,
+                "accepts_from_names" => ["In Progress", "QA"],
+                "on_entry" => [{ "action" => "mark_pr_ready" }],
+                "on_entry_text" => "Take the PR out of draft — mark it ready for review on GitHub." } },
+    { name: "QA",          archetype: "review",
+      policy: { "ai" => true, "plan_approval" => false,
+                "accepts_from_names" => ["Review"],
+                "on_entry" => [{ "action" => "mark_pr_ready" }] } },
+    { name: "Done",        archetype: "terminal",
+      policy: { "ai" => false, "plan_approval" => false, "arrivals" => "top",
+                "accepts_from_names" => ["Review", "QA", "Planning"],
+                "on_entry" => [{ "action" => "merge_pr" }] } }
+  ].freeze
+  # Create the default columns, then resolve accepts_from_names -> ids.
+  def install_default_columns!
+    DEFAULT_COLUMNS.each_with_index do |attrs, index|
+      columns.create!(name: attrs[:name], archetype: attrs[:archetype], position: index,
+                      policy: attrs[:policy].except("accepts_from_names"))
+    end
+    DEFAULT_COLUMNS.each do |attrs|
+      names = attrs[:policy]["accepts_from_names"] or next
+      col = columns.find_by!(name: attrs[:name])
+      ids = columns.where(name: names).pluck(:id).map(&:to_s)
+      col.update!(policy: col.policy.merge("accepts_from" => ids))
+    end
+  end
+  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
+    )
+    board.install_default_columns!
+    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? && column.ai?
+    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