brainiac-fizzy 0.0.1

data/lib/brainiac/plugins/fizzy/handlers/dedup.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+# Card duplicate detection (card_published / card_triaged).
+#
+# When a new card is created, checks for similar existing cards using
+# trigram and semantic similarity. Posts a warning comment if duplicates found.
+
+def handle_card_published(payload)
+  eventable = payload["eventable"] || {}
+  card_number = eventable["number"]
+  title = eventable["title"] || ""
+  creator_name = payload.dig("creator", "name")
+  creator_id = payload.dig("creator", "id")
+  tags = eventable["tags"] || []
+
+  # Creator-based routing: only the machine whose local human created the card
+  # handles dedup. Requires `"local": true` on the human in fizzy.json authorized_users.
+  local_humans = FIZZY_CONFIG.fetch("authorized_users", []).select { |u| u["human"] && u["local"] }
+  if local_humans.empty?
+    LOG.info "[CardIndex] No local humans configured — skipping dedup, indexing only"
+    return index_card_only(card_number, title, creator_name, creator_id, tags)
+  end
+
+  unless local_humans.any? { |u| u["id"] == creator_id }
+    LOG.info "[CardIndex] Ignoring card ##{card_number} — creator '#{creator_name}' is not a local human"
+    return index_card_only(card_number, title, creator_name, creator_id, tags)
+  end
+
+  # Check for duplicates before indexing
+  similar = CARD_INDEX.find_similar_cards(title, exclude_number: card_number, tags: tags) if card_number
+  index_card_only(card_number, title, creator_name, creator_id, tags, skip_response: true)
+
+  if similar&.any?
+    post_duplicate_warning(card_number, title, tags, similar)
+    [200, { status: "duplicate_detected", card: card_number,
+            similar: similar.map { |s| { number: s[:number], score: s[:score].round(2) } } }.to_json]
+  else
+    LOG.info "[CardIndex] Card ##{card_number} '#{title}' indexed, no duplicates found"
+    [200, { status: "indexed", card: card_number }.to_json]
+  end
+end
+
+def index_card_only(card_number, title, creator_name, creator_id, tags, skip_response: false)
+  CARD_INDEX.index_card(number: card_number, title: title, creator_name: creator_name, creator_id: creator_id, tags: tags) if card_number
+  CARD_INDEX.save
+  CARD_INDEX.schedule_qmd_reindex
+  [200, { status: "indexed", card: card_number }.to_json] unless skip_response
+end
+
+def post_duplicate_warning(card_number, title, tags, similar)
+  best = similar.first
+  LOG.info "[CardIndex] Potential duplicate: ##{card_number} '#{title}' ≈ " \
+           "##{best[:number]} '#{best[:title]}' (score: #{best[:score].round(2)})"
+
+  project_result = identify_project_by_tags(tags)
+  return unless project_result
+
+  _project_key, project_config = project_result
+  repo_path = project_config["repo_path"]
+
+  Thread.new do
+    method_label = { trigram: "📝", semantic: "🧠", both: "📝🧠" }
+    dupes = similar.map do |s|
+      icon = method_label[s[:method]] || "📝"
+      "##{s[:number]} \"#{s[:title]}\" (#{(s[:score] * 100).round}% #{icon})"
+    end.join("\n- ")
+    body = "⚠️ **Possible duplicate detected:**\n- #{dupes}\n\n_📝 = text similarity, 🧠 = semantic similarity_"
+    run_cmd("fizzy", "comment", "create", "--card", card_number.to_s, "--body", body,
+            chdir: repo_path, env: default_fizzy_env)
+    LOG.info "[CardIndex] Posted duplicate warning on card ##{card_number}"
+  rescue StandardError => e
+    LOG.warn "[CardIndex] Failed to post duplicate warning: #{e.message}"
+  end
+end

data/lib/brainiac/plugins/fizzy/handlers/deploy.rb

@@ -0,0 +1,152 @@
+# frozen_string_literal: true
+
+# Fizzy deploy comment handler.
+#
+# When a comment is just "dev02" (or any dev\d+), deploy the card's
+# worktree to that environment. No agent dispatch — reactions only.
+
+def handle_deploy_comment(eventable, env_key, card_internal_id)
+  comment_id = eventable["id"]
+  card_info = load_card_map[card_internal_id]
+
+  # Validate environment exists
+  deploy_config = DEPLOYMENTS_CONFIG["environments"] || {}
+  unless deploy_config.key?(env_key)
+    LOG.warn "[Deploy] Unknown environment: #{env_key}"
+    return [200, { status: "ignored", reason: "unknown environment" }.to_json]
+  end
+
+  # Check environment ownership
+  env_owner = deploy_config[env_key]["owner"]
+  unless env_owner && env_owner.downcase == AI_AGENT_NAME.downcase
+    LOG.info "[Deploy] Skipping #{env_key} — owner is #{env_owner.inspect}, this machine is #{AI_AGENT_NAME}"
+    return [200, { status: "ignored", reason: env_owner ? "owned by #{env_owner}" : "no owner configured" }.to_json]
+  end
+
+  worktree = card_info&.dig("worktree")
+  card_number = card_info&.dig("number")
+
+  # If worktree doesn't exist locally, try to clone the branch from origin
+  if worktree.nil? || !File.directory?(worktree)
+    result = clone_branch_for_deploy(eventable, card_internal_id, card_info)
+    unless result
+      LOG.warn "[Deploy] Could not resolve or clone branch for card #{card_internal_id}"
+      return [200, { status: "ignored", reason: "no worktree and could not clone branch" }.to_json]
+    end
+    worktree = result[:worktree]
+    card_number = result[:card_number]
+  end
+
+  deploy_script = File.join(worktree, "scripts", "deploy.sh")
+  unless File.exist?(deploy_script)
+    LOG.warn "[Deploy] No deploy script at #{deploy_script}"
+    return [200, { status: "ignored", reason: "no deploy script" }.to_json]
+  end
+
+  LOG.info "[Deploy] Deploying card ##{card_number} worktree to #{env_key}"
+  mark_deploying(env_key, worktree_path: worktree)
+
+  Thread.new do
+    react_to_deploy(card_number, comment_id, worktree, "🚀")
+    run_deploy(env_key, card_number, comment_id, worktree)
+  rescue StandardError => e
+    LOG.error "[Deploy] Error deploying card ##{card_number} to #{env_key}: #{e.message}"
+    react_to_deploy(card_number, comment_id, worktree, "❌")
+  end
+
+  [200, { status: "deploying", card: card_number, env: env_key }.to_json]
+end
+
+def react_to_deploy(card_number, comment_id, worktree, emoji)
+  run_cmd("fizzy", "reaction", "create", "--card", card_number.to_s,
+          "--comment", comment_id.to_s, "--content", emoji,
+          chdir: worktree, env: default_fizzy_env)
+rescue StandardError => e
+  LOG.warn "[Deploy] Could not add reaction #{emoji}: #{e.message}"
+end
+
+def run_deploy(env_key, card_number, comment_id, worktree)
+  deploy_env = {}
+  aws_profile = DEPLOYMENTS_CONFIG.dig("environments", env_key, "aws_profile")
+  deploy_env["AWS_PROFILE"] = aws_profile if aws_profile
+
+  stdout, stderr, status = Open3.capture3(deploy_env, "./scripts/deploy.sh", env_key, chdir: worktree)
+
+  if !status.success? && terraform_lock_error?(stdout, stderr)
+    stdout, stderr, status = retry_deploy_with_init(deploy_env, env_key, card_number, worktree)
+  end
+
+  if status.success?
+    LOG.info "[Deploy] Successfully deployed card ##{card_number} to #{env_key}"
+    react_to_deploy(card_number, comment_id, worktree, "✅")
+    deploy_to_environment(env_key, worktree_path: worktree, deployed_by: "fizzy-comment")
+  else
+    LOG.error "[Deploy] Failed deploying card ##{card_number} to #{env_key}: #{stderr}"
+    react_to_deploy(card_number, comment_id, worktree, "❌")
+    record_deploy_failure(env_key, worktree_path: worktree, stdout: stdout, stderr: stderr)
+  end
+end
+
+def retry_deploy_with_init(deploy_env, env_key, card_number, worktree)
+  LOG.info "[Deploy] Terraform lock file mismatch for card ##{card_number} — retrying with init -upgrade"
+  infra_dir = File.join(worktree, "infrastructure", env_key)
+  lock_file = File.join(infra_dir, ".terraform.lock.hcl")
+  FileUtils.rm_f(lock_file)
+  Open3.capture3(deploy_env, "terraform", "init", "-upgrade", chdir: infra_dir) if File.directory?(infra_dir)
+  Open3.capture3(deploy_env, "./scripts/deploy.sh", env_key, chdir: worktree)
+end
+
+# Clone a remote branch locally for deploy when the worktree doesn't exist on this machine.
+# Returns { worktree:, card_number: } on success, nil on failure.
+def clone_branch_for_deploy(eventable, card_internal_id, card_info)
+  card_tags = eventable.dig("card", "tags") || []
+  project_result = identify_project_by_tags(card_tags)
+  unless project_result
+    LOG.warn "[Deploy] Cannot identify project for card #{card_internal_id}"
+    return nil
+  end
+  project_key, project_config = project_result
+  repo_path = project_config["repo_path"]
+
+  card_number = card_info&.dig("number")
+  card_number ||= resolve_card_number(card_internal_id, repo_path: repo_path)
+  unless card_number
+    LOG.warn "[Deploy] Cannot resolve card number for #{card_internal_id}"
+    return nil
+  end
+
+  debounced_repo_fetch(repo_path)
+  branches = run_cmd("git", "branch", "-r", "--list", "origin/fizzy-#{card_number}-*", chdir: repo_path).strip
+  branch = branches.lines.map(&:strip).first&.sub("origin/", "")
+  unless branch
+    LOG.warn "[Deploy] No remote branch matching fizzy-#{card_number}-* found"
+    return nil
+  end
+
+  worktree_path = File.join(File.dirname(repo_path), "#{File.basename(repo_path)}--#{branch}")
+
+  unless File.directory?(worktree_path)
+    branch_exists_locally = system("git", "rev-parse", "--verify", branch, chdir: repo_path, out: File::NULL, err: File::NULL)
+    if branch_exists_locally
+      run_cmd("git", "worktree", "add", worktree_path, branch, chdir: repo_path)
+    else
+      run_cmd("git", "worktree", "add", "--track", "-b", branch, worktree_path, "origin/#{branch}", chdir: repo_path)
+    end
+
+    trust_version_manager(worktree_path, chdir: worktree_path)
+    apply_worktree_includes(repo_path, worktree_path)
+    run_project_hook(repo_path, "worktree-setup", extra_env: { "WORKTREE_PATH" => worktree_path })
+  end
+
+  # Update card map
+  map = load_card_map
+  map[card_internal_id] ||= {}
+  map[card_internal_id].merge!("number" => card_number, "branch" => branch, "worktree" => worktree_path, "project" => project_key)
+  save_card_map(map)
+
+  LOG.info "[Deploy] Cloned branch #{branch} into worktree #{worktree_path} for card ##{card_number}"
+  { worktree: worktree_path, card_number: card_number }
+rescue StandardError => e
+  LOG.error "[Deploy] Failed to clone branch for card #{card_internal_id}: #{e.message}"
+  nil
+end

data/lib/brainiac/plugins/fizzy/handlers/deployments.rb

@@ -0,0 +1,260 @@
+# frozen_string_literal: true
+
+require "shellwords"
+
+# Deployment environment tracking.
+# Tracks which dev environments have active card deploys and which are available.
+
+DEPLOYMENTS_CONFIG_FILE = File.join(BRAINIAC_DIR, "deployments.json")
+DEPLOYMENT_STATE_FILE   = File.join(BRAINIAC_DIR, "deployment_state.json")
+
+def load_deployments_config
+  return {} unless File.exist?(DEPLOYMENTS_CONFIG_FILE)
+
+  JSON.parse(File.read(DEPLOYMENTS_CONFIG_FILE))
+rescue JSON::ParserError => e
+  LOG.error "Failed to parse deployments config: #{e.message}"
+  {}
+end
+
+def load_deployment_state
+  return {} unless File.exist?(DEPLOYMENT_STATE_FILE)
+
+  JSON.parse(File.read(DEPLOYMENT_STATE_FILE))
+rescue JSON::ParserError => e
+  LOG.error "Failed to parse deployment state: #{e.message}"
+  {}
+end
+
+def save_deployment_state(state)
+  File.write(DEPLOYMENT_STATE_FILE, JSON.pretty_generate(state))
+end
+
+DEPLOYMENTS_CONFIG = load_deployments_config
+DEPLOYMENT_STATE   = load_deployment_state
+
+def reload_deployments_config!(force: false)
+  return unless file_changed?(DEPLOYMENTS_CONFIG_FILE, force: force)
+
+  DEPLOYMENTS_CONFIG.replace(load_deployments_config)
+end
+
+def reload_deployment_state!(force: false)
+  return unless file_changed?(DEPLOYMENT_STATE_FILE, force: force)
+
+  DEPLOYMENT_STATE.replace(load_deployment_state)
+end
+
+# Mark an environment as actively deploying (in-progress state for waybar).
+def mark_deploying(env_key, worktree_path:)
+  state = load_deployment_state
+  state[env_key] ||= {}
+  state[env_key]["status"] = "occupied"
+  state[env_key]["last_deploy_status"] = "deploying"
+  state[env_key]["last_deploy_at"] = Time.now.iso8601
+  save_deployment_state(state)
+  DEPLOYMENT_STATE.replace(state)
+end
+
+# Mark an environment as occupied. Resolves card info from the card map using the worktree path.
+def deploy_to_environment(env_key, worktree_path:, deployed_by: nil)
+  config = DEPLOYMENTS_CONFIG["environments"] || {}
+  unless config.key?(env_key)
+    LOG.warn "[Deploy] Unknown environment: #{env_key}"
+    return { error: "Unknown environment: #{env_key}" }
+  end
+
+  state = load_deployment_state
+  entry = { "status" => "occupied", "deployed_at" => Time.now.iso8601, "deployed_by" => deployed_by,
+            "last_deploy_status" => "success", "last_deploy_at" => Time.now.iso8601 }
+
+  # Resolve card info from card map by matching worktree path
+  map = load_card_map
+  card_entry = map.values.find { |info| info["worktree"] == worktree_path }
+  if card_entry
+    entry["card_number"] = card_entry["number"]
+    entry["card_title"]  = card_entry["title"]
+    entry["branch"]      = card_entry["branch"]
+    pr = (card_entry["prs"] || []).last
+    if pr
+      entry["pr_number"] = pr["number"]
+      entry["pr_url"]    = pr["url"]
+    end
+    # Store card tags for URL resolution (e.g. ops-web-app → ops URL)
+    if defined?(CARD_INDEX)
+      card_idx = CARD_INDEX[card_entry["number"].to_s]
+      entry["card_tags"] = card_idx["tags"] if card_idx && card_idx["tags"]
+    end
+  else
+    # No card map match — record branch from git
+    branch = `git -C #{Shellwords.escape(worktree_path)} rev-parse --abbrev-ref HEAD 2>/dev/null`.strip
+    entry["branch"] = branch unless branch.empty?
+  end
+
+  commit = `git -C #{Shellwords.escape(worktree_path)} rev-parse --short HEAD 2>/dev/null`.strip
+  entry["commit"] = commit unless commit.empty?
+
+  state[env_key] = entry
+  save_deployment_state(state)
+  DEPLOYMENT_STATE.replace(state)
+  LOG.info "[Deploy] #{env_key} marked occupied — card ##{entry["card_number"] || "none"}, branch: #{entry["branch"]}"
+  entry
+end
+
+DEPLOY_LOGS_DIR = File.join(BRAINIAC_DIR, "deploy_logs")
+
+# Record a failed deploy — saves output to a log file and updates state.
+def record_deploy_failure(env_key, worktree_path:, stdout: "", stderr: "")
+  FileUtils.mkdir_p(DEPLOY_LOGS_DIR)
+  log_file = File.join(DEPLOY_LOGS_DIR, "#{env_key}-#{Time.now.strftime("%Y%m%d-%H%M%S")}.log")
+  File.write(log_file, "=== STDOUT ===\n#{stdout}\n\n=== STDERR ===\n#{stderr}")
+
+  state = load_deployment_state
+  state[env_key] ||= {}
+  state[env_key]["last_deploy_status"] = "failed"
+  state[env_key]["last_deploy_at"] = Time.now.iso8601
+  state[env_key]["last_deploy_log"] = log_file
+  save_deployment_state(state)
+  DEPLOYMENT_STATE.replace(state)
+  LOG.info "[Deploy] #{env_key} deploy failed — log at #{log_file}"
+end
+
+# Auto-deploy after agent session when [deploy] tag was present.
+# deploy_intent is either a specific env key (e.g. "dev04"), :auto (auto-detect), or nil (no deploy).
+def auto_deploy_after_session(deploy_intent:, card_internal_id:, card_number:, worktree_path:, agent_name:)
+  state = load_deployment_state
+  config = DEPLOYMENTS_CONFIG["environments"] || {}
+
+  env_key = resolve_deploy_environment(deploy_intent, state, card_number)
+  return unless env_key
+
+  unless config.key?(env_key)
+    LOG.warn "[Deploy] Auto-deploy skipped — unknown environment: #{env_key}"
+    return
+  end
+
+  env_owner = config[env_key]["owner"]
+  unless env_owner && env_owner.downcase == AI_AGENT_NAME.downcase
+    LOG.info "[Deploy] Auto-deploy skipped #{env_key} — owner is #{env_owner.inspect}, this machine is #{AI_AGENT_NAME}"
+    return
+  end
+
+  deploy_script = File.join(worktree_path, "scripts", "deploy.sh")
+  unless File.exist?(deploy_script)
+    LOG.warn "[Deploy] Auto-deploy skipped — no deploy script at #{deploy_script}"
+    return
+  end
+
+  LOG.info "[Deploy] Auto-deploying card ##{card_number} to #{env_key} (triggered by [deploy] tag)"
+  mark_deploying(env_key, worktree_path: worktree_path)
+
+  deploy_env = {}
+  aws_profile = config.dig(env_key, "aws_profile")
+  deploy_env["AWS_PROFILE"] = aws_profile if aws_profile
+
+  run_deploy(deploy_env, deploy_script, env_key, worktree_path: worktree_path, card_number: card_number, agent_name: agent_name)
+end
+
+# Resolve which environment to deploy to from the intent.
+def resolve_deploy_environment(deploy_intent, state, card_number)
+  if deploy_intent.is_a?(String) && !deploy_intent.empty?
+    deploy_intent
+  else
+    existing = state.find { |_k, v| v["card_number"] == card_number && v["status"] == "occupied" }&.first
+    LOG.info "[Deploy] Auto-deploy skipped — card ##{card_number} not currently deployed to any environment" unless existing
+    existing
+  end
+end
+
+# Execute deploy script with terraform lock retry logic.
+def run_deploy(deploy_env, deploy_script, env_key, worktree_path:, card_number:, agent_name:)
+  stdout, stderr, status = Open3.capture3(deploy_env, deploy_script, env_key, chdir: worktree_path)
+
+  if status.success?
+    deploy_to_environment(env_key, worktree_path: worktree_path, deployed_by: "#{agent_name} [deploy]")
+    LOG.info "[Deploy] Auto-deploy to #{env_key} succeeded for card ##{card_number}"
+  elsif terraform_lock_error?(stdout, stderr)
+    retry_deploy_after_lock_fix(deploy_env, deploy_script, env_key, worktree_path: worktree_path, card_number: card_number, agent_name: agent_name)
+  else
+    record_deploy_failure(env_key, worktree_path: worktree_path, stdout: stdout, stderr: stderr)
+    LOG.error "[Deploy] Auto-deploy to #{env_key} failed for card ##{card_number}"
+  end
+end
+
+# Retry deploy after clearing terraform lock.
+def retry_deploy_after_lock_fix(deploy_env, deploy_script, env_key, worktree_path:, card_number:, agent_name:)
+  lock_file = File.join(worktree_path, "infrastructure/#{env_key}/.terraform.lock.hcl")
+  FileUtils.rm_f(lock_file)
+  Open3.capture3("terraform", "init", "-upgrade", chdir: File.join(worktree_path, "infrastructure/#{env_key}"))
+  stdout2, stderr2, status2 = Open3.capture3(deploy_env, deploy_script, env_key, chdir: worktree_path)
+  if status2.success?
+    deploy_to_environment(env_key, worktree_path: worktree_path, deployed_by: "#{agent_name} [deploy]")
+    LOG.info "[Deploy] Auto-deploy to #{env_key} succeeded (after terraform lock fix) for card ##{card_number}"
+  else
+    record_deploy_failure(env_key, worktree_path: worktree_path, stdout: stdout2, stderr: stderr2)
+    LOG.error "[Deploy] Auto-deploy to #{env_key} failed (after retry) for card ##{card_number}"
+  end
+end
+
+# Detect Terraform provider lock file checksum mismatch errors.
+def terraform_lock_error?(stdout, stderr)
+  combined = "#{stdout}\n#{stderr}"
+  combined.include?("checksums previously recorded in the dependency lock file")
+end
+
+# Clear all environments occupied by a given card number (called on PR merge).
+def clear_deployment_for_card(card_number)
+  state = load_deployment_state
+  cleared = []
+
+  state.each do |env_key, info|
+    next unless info["card_number"] == card_number && info["status"] == "occupied"
+
+    state[env_key] = { "status" => "available", "cleared_at" => Time.now.iso8601, "last_card" => card_number }
+    cleared << env_key
+  end
+
+  if cleared.any?
+    save_deployment_state(state)
+    DEPLOYMENT_STATE.replace(state)
+    LOG.info "[Deploy] Cleared #{cleared.join(", ")} — card ##{card_number} merged"
+  end
+
+  cleared
+end
+
+# Return environments with status "available", optionally filtered by project.
+def available_environments(project: nil)
+  config = DEPLOYMENTS_CONFIG["environments"] || {}
+  state = load_deployment_state
+
+  config.select do |env_key, env_config|
+    next false if project && env_config["project"] != project
+
+    info = state[env_key]
+    info.nil? || info["status"] == "available"
+  end.keys
+end
+
+# Full deployment status for API / waybar.
+def deployment_status
+  config = DEPLOYMENTS_CONFIG["environments"] || {}
+  state = load_deployment_state
+
+  config.map do |env_key, env_config|
+    info = state[env_key] || { "status" => "available" }
+    url = resolve_deployment_url(env_config, info["card_tags"])
+    { "env" => env_key, "label" => env_config["label"], "url" => url, "project" => env_config["project"] }.merge(info)
+  end
+end
+
+# Resolve the correct URL for an environment based on card tags.
+# If the card has a tag matching a key in the environment's "urls" map, use that URL.
+# Otherwise fall back to the default "url".
+def resolve_deployment_url(env_config, card_tags)
+  urls = env_config["urls"] || {}
+  if card_tags && urls.any?
+    card_tags.each { |tag| return urls[tag] if urls[tag] }
+  end
+  env_config["url"]
+end

data/lib/brainiac/plugins/fizzy/helpers.rb

@@ -0,0 +1,165 @@
+# frozen_string_literal: true
+
+module Brainiac
+  module Plugins
+    module Fizzy
+      # Fizzy-specific helper functions.
+      # These were previously in lib/brainiac/helpers.rb in core.
+      module Helpers
+        class << self
+          # Returns true if signature is valid (or no secret configured).
+          # Returns false if signature verification fails.
+          def verify_signature!(request, payload_body, board_key: nil)
+            signature = request.env["HTTP_X_WEBHOOK_SIGNATURE"]
+            return false unless signature
+
+            secret = board_key ? Config.board_webhook_secret(board_key) : ENV.fetch("FIZZY_WEBHOOK_SECRET", nil)
+            return false unless secret
+
+            computed = OpenSSL::HMAC.hexdigest("sha256", secret, payload_body)
+            Rack::Utils.secure_compare(signature, computed)
+          end
+
+          def fizzy_token_for(agent_name)
+            agent_env_var(agent_name, "FIZZY_TOKEN")
+          end
+
+          def fizzy_env_for(agent_name)
+            token = fizzy_token_for(agent_name) || fizzy_token_for(AI_AGENT_NAME)
+            token ? { "FIZZY_TOKEN" => token } : {}
+          end
+
+          def default_fizzy_env
+            fizzy_env_for(AI_AGENT_NAME)
+          end
+
+          def prefetch_card_context(card_number, repo_path:, agent_name: nil)
+            env = fizzy_env_for(agent_name || AI_AGENT_NAME)
+            card_details = fetch_card_details(card_number, repo_path: repo_path, env: env)
+            card_comments = fetch_card_comments(card_number, repo_path: repo_path, env: env)
+
+            context = ""
+            context += "## Card Details\n#{card_details}\n\n" unless card_details.empty?
+            context += "## Recent Comments\n#{card_comments}\n" unless card_comments.empty?
+            context
+          end
+
+          def fetch_card_details(card_number, repo_path:, env:)
+            output = run_cmd("fizzy", "card", "show", card_number.to_s, chdir: repo_path, env: env)
+            card = JSON.parse(output)["data"]
+            return "" unless card
+
+            parts = []
+            parts << "**Title:** #{card["title"]}"
+            parts << "**Body:**\n#{card.dig("body", "plain_text")}" if card.dig("body", "plain_text")
+            parts.join("\n")
+          rescue StandardError => e
+            LOG.warn "[Fizzy] Could not fetch card ##{card_number}: #{e.message}" if defined?(LOG)
+            ""
+          end
+
+          def fetch_card_comments(card_number, repo_path:, env:)
+            output = run_cmd("fizzy", "comment", "list", "--card", card_number.to_s, chdir: repo_path, env: env)
+            comments = JSON.parse(output)["data"] || []
+            return "" if comments.empty?
+
+            comments.last(15).map do |c|
+              body = c.dig("body", "plain_text") || ""
+              body = "#{body[0..500]}..." if body.length > 500
+              "**#{c["creator_name"]}** (#{c["id"]}):\n#{body}"
+            end.join("\n\n---\n\n")
+          rescue StandardError => e
+            LOG.warn "[Fizzy] Could not fetch comments for card ##{card_number}: #{e.message}" if defined?(LOG)
+            ""
+          end
+
+          def move_card_to_column(card_number, column_name, project_config:, agent_name: nil)
+            board_key = Config.board_key_for_project(project_config)
+            column_id = Config.board_column_id(board_key, column_name) if board_key
+            return unless column_id
+
+            repo_path = project_config["repo_path"]
+            env = fizzy_env_for(agent_name || AI_AGENT_NAME)
+            run_cmd("fizzy", "card", "column", card_number.to_s, "--column", column_id, chdir: repo_path, env: env)
+          end
+
+          def append_fizzy_comment_footer(card_number, project_config:, agent_name: nil)
+            repo_path = project_config["repo_path"]
+            env = fizzy_env_for(agent_name || AI_AGENT_NAME)
+
+            output = run_cmd("fizzy", "comment", "list", "--card", card_number.to_s, chdir: repo_path, env: env)
+            comments = JSON.parse(output)["data"] || []
+            agent_display = agent_display_name(agent_name || AI_AGENT_NAME)
+
+            last_agent_comment = comments.reverse.find do |c|
+              c["creator_name"]&.downcase == agent_display.downcase
+            end
+            return unless last_agent_comment
+
+            # Check if footer already exists
+            body = last_agent_comment.dig("body", "html") || ""
+            return if body.include?("<em>Branch:")
+
+            # Detect branch from comment content or card map
+            branch = detect_branch_from_comment(body, card_number)
+            return unless branch
+
+            pr_url = detect_pr_url(branch, project_config)
+            footer = "<p><em>Branch: <code>#{branch}</code>"
+            footer += " | <a href=\"#{pr_url}\">PR</a>" if pr_url
+            footer += "</em></p>"
+
+            updated_body = body + footer
+            run_cmd("fizzy", "comment", "update", last_agent_comment["id"], "--card", card_number.to_s,
+                    "--body", updated_body, chdir: repo_path, env: env)
+          rescue StandardError => e
+            LOG.warn "[Fizzy] Could not append footer to card ##{card_number}: #{e.message}" if defined?(LOG)
+          end
+
+          def ensure_fizzy_yaml!(chdir, project_config)
+            fizzy_yaml_dest = File.join(chdir, ".fizzy.yaml")
+            return if File.exist?(fizzy_yaml_dest)
+
+            fizzy_yaml_src = File.join(project_config["repo_path"], ".fizzy.yaml")
+            return unless File.exist?(fizzy_yaml_src)
+
+            FileUtils.cp(fizzy_yaml_src, fizzy_yaml_dest)
+            LOG.info "[Fizzy] Copied .fizzy.yaml to #{chdir}" if defined?(LOG)
+          end
+
+          def scrub_invalid_attachments!(dir)
+            attachments_dir = File.join(dir, ".fizzy-attachments")
+            return unless Dir.exist?(attachments_dir)
+
+            Dir.glob(File.join(attachments_dir, "*")).each do |file|
+              next unless File.file?(file)
+              next if File.size(file) > 100 # Keep files with real content
+
+              File.delete(file)
+            end
+          end
+
+          private
+
+          def detect_branch_from_comment(body, card_number)
+            # Try to find branch in comment body
+            match = body.match(%r{<code>(fizzy-#{card_number}-[^<]+)</code>})
+            return match[1] if match
+
+            # Fall back to card map
+            map = load_work_item_map
+            entry = map.values.find { |v| v["number"].to_s == card_number.to_s }
+            entry&.dig("branch")
+          end
+
+          def detect_pr_url(branch, project_config)
+            repo = project_config["github_repo"]
+            return nil unless repo
+
+            "https://github.com/#{repo}/pull/new/#{branch}"
+          end
+        end
+      end
+    end
+  end
+end