agentboard 0.2.0

data/app/models/agentboard/ticket.rb

@@ -0,0 +1,81 @@
+module Agentboard
+  class Ticket < ApplicationRecord
+    KINDS = %w[feature bug task chore spike].freeze
+    PRIORITIES = { 0 => "Urgent", 1 => "High", 2 => "Medium", 3 => "Low" }.freeze
+    KEY_FORMAT = /\A([A-Z][A-Z0-9_-]*)-(\d+)\z/
+
+    belongs_to :project
+    belongs_to :milestone, optional: true
+    belongs_to :parent, class_name: "Agentboard::Ticket", optional: true
+    has_many :subtasks, class_name: "Agentboard::Ticket", foreign_key: :parent_id, dependent: :nullify
+    has_many :acceptance_criteria, -> { order(:position) }, class_name: "Agentboard::AcceptanceCriterion", dependent: :destroy
+    has_many :comments, -> { order(:created_at) }, dependent: :destroy
+    has_many :dependencies, class_name: "Agentboard::TicketDependency", dependent: :destroy
+    has_many :depends_on, through: :dependencies, source: :depends_on_ticket
+    has_many :inverse_dependencies, class_name: "Agentboard::TicketDependency", foreign_key: :depends_on_ticket_id, dependent: :destroy
+    has_many :dependents, through: :inverse_dependencies, source: :ticket
+    has_many :leases, class_name: "Agentboard::TicketLease", dependent: :destroy
+    has_many :session_links, class_name: "Agentboard::SessionTicketLink", dependent: :destroy
+    has_many :agent_sessions, through: :session_links # no DISTINCT: PostgreSQL has no equality for json columns
+    has_many :executions, -> { order(created_at: :desc) }, dependent: :restrict_with_exception
+    has_many :artifacts, -> { order(created_at: :desc) }, dependent: :destroy
+    has_many :workflow_runs, dependent: :restrict_with_exception
+    belongs_to :assignee_profile, class_name: "Agentboard::AgentProfile", optional: true
+
+    validates :title, presence: true, length: { maximum: 255 }
+    validates :number, presence: true, uniqueness: { scope: :project_id }
+    validates :kind, inclusion: { in: KINDS }
+    validates :status, inclusion: { in: StateMachines::Ticket::STATES }
+    validates :priority, inclusion: { in: PRIORITIES.keys }
+
+    scope :open, -> { where.not(status: StateMachines::Ticket::TERMINAL) }
+    scope :ordered, -> { order(:priority, :position, :number) }
+
+    def self.find_by_key!(key, project: nil)
+      match = KEY_FORMAT.match(key.to_s.strip.upcase)
+      raise Agentboard::Error.not_found("Ticket #{key} not found") unless match
+
+      scope = joins(:project).where(agentboard_projects: { key: match[1] }, number: match[2].to_i)
+      scope = scope.where(project_id: project.id) if project
+      scope.first or raise Agentboard::Error.not_found("Ticket #{key} not found")
+    end
+
+    def self.find_by_key(key, project: nil)
+      find_by_key!(key, project: project)
+    rescue Agentboard::Error
+      nil
+    end
+
+    def key = "#{project.key}-#{number}"
+    def to_param = key
+    def priority_label = PRIORITIES[priority]
+    def status_label = StateMachines::Ticket::LABELS[status]
+    def terminal? = StateMachines::Ticket::TERMINAL.include?(status)
+
+    def active_lease
+      leases.where(released_at: nil).where("expires_at > ?", Time.current).first
+    end
+
+    def active_execution = executions.where(status: StateMachines::Execution::ACTIVE).first
+
+    def dependencies_satisfied?
+      depends_on.where.not(status: "done").none?
+    end
+
+    def unsatisfied_dependencies = depends_on.where.not(status: "done")
+
+    def criteria_progress
+      total = acceptance_criteria.size
+      done = acceptance_criteria.count { |c| %w[verified waived].include?(c.state) }
+      [ done, total ]
+    end
+
+    def events
+      Agentboard::Event.where(ticket_id: id).order(:occurred_at, :sequence)
+    end
+
+    def latest_head_sha
+      executions.where.not(head_sha: nil).pick(:head_sha)
+    end
+  end
+end

data/app/models/agentboard/ticket_dependency.rb

@@ -0,0 +1,34 @@
+module Agentboard
+  class TicketDependency < ApplicationRecord
+    KINDS = %w[blocks relates].freeze
+
+    belongs_to :ticket
+    belongs_to :depends_on_ticket, class_name: "Agentboard::Ticket"
+
+    validates :kind, inclusion: { in: KINDS }
+    validates :depends_on_ticket_id, uniqueness: { scope: [ :ticket_id, :kind ] }
+    validate :not_self
+    validate :acyclic, if: -> { kind == "blocks" }
+
+    private
+
+    def not_self
+      errors.add(:depends_on_ticket, "cannot be the ticket itself") if ticket_id == depends_on_ticket_id
+    end
+
+    # DAG validation: adding ticket -> dep must not create a path dep ->* ticket.
+    def acyclic
+      seen = Set.new
+      frontier = [ depends_on_ticket_id ]
+      while (current = frontier.shift)
+        if current == ticket_id
+          errors.add(:depends_on_ticket, "would create a dependency cycle")
+          return
+        end
+        next unless seen.add?(current)
+
+        frontier.concat(self.class.where(ticket_id: current, kind: "blocks").pluck(:depends_on_ticket_id))
+      end
+    end
+  end
+end

data/app/models/agentboard/ticket_lease.rb

@@ -0,0 +1,11 @@
+module Agentboard
+  class TicketLease < ApplicationRecord
+    belongs_to :ticket
+    belongs_to :agent_session, optional: true
+
+    scope :live, -> { where(released_at: nil) }
+
+    def expired?(now = Time.current) = expires_at <= now
+    def active?(now = Time.current) = released_at.nil? && !expired?(now)
+  end
+end

data/app/models/agentboard/usage_record.rb

@@ -0,0 +1,10 @@
+module Agentboard
+  # Token/cost metering. Unknown cost is nil, never zero; monetary amounts require
+  # provenance. `metering_kind` distinguishes API-billed from subscription CLI usage.
+  class UsageRecord < ApplicationRecord
+    METERING_KINDS = %w[api_billed subscription unknown].freeze
+    belongs_to :execution
+    validates :metering_kind, inclusion: { in: METERING_KINDS }
+    validates :source, presence: true
+  end
+end

data/app/models/agentboard/verification_result.rb

@@ -0,0 +1,12 @@
+module Agentboard
+  # A check bound to a specific commit. A result for SHA A never authorizes SHA B (AT-08).
+  class VerificationResult < ApplicationRecord
+    STATUSES = %w[running passed failed error timeout skipped].freeze
+    belongs_to :execution
+    validates :status, inclusion: { in: STATUSES }
+    validates :commit_sha, :command_digest, :name, presence: true
+
+    def passed? = status == "passed"
+    def stale_for?(head_sha) = commit_sha != head_sha
+  end
+end

data/app/models/agentboard/webhook_delivery.rb

@@ -0,0 +1,7 @@
+module Agentboard
+  class WebhookDelivery < ApplicationRecord
+    STATUSES = %w[received processed ignored rejected failed].freeze
+    validates :provider, :delivery_id, :event, :payload_digest, presence: true
+    validates :status, inclusion: { in: STATUSES }
+  end
+end

data/app/models/agentboard/workflow_definition.rb

@@ -0,0 +1,20 @@
+module Agentboard
+  # Immutable once used: a changed definition is registered as a new version.
+  class WorkflowDefinition < ApplicationRecord
+    belongs_to :project
+    has_many :workflow_runs, dependent: :restrict_with_exception
+    validates :name, :version, :digest, presence: true
+
+    before_update :prevent_mutation_when_used
+
+    def parsed = Agentboard::Workflows::Definition.from_h(definition)
+
+    private
+
+    def prevent_mutation_when_used
+      return unless workflow_runs.exists? && (definition_changed? || digest_changed?)
+
+      raise Agentboard::Error.validation_failed("Workflow #{name} v#{version} is immutable once used")
+    end
+  end
+end

data/app/models/agentboard/workflow_run.rb

@@ -0,0 +1,21 @@
+module Agentboard
+  class WorkflowRun < ApplicationRecord
+    STATUSES = %w[pending running waiting_for_approval succeeded failed cancelled].freeze
+    TERMINAL = %w[succeeded failed cancelled].freeze
+
+    belongs_to :workflow_definition
+    belongs_to :ticket
+    has_many :steps, -> { order(:created_at) }, class_name: "Agentboard::WorkflowStep", dependent: :destroy
+
+    validates :status, inclusion: { in: STATUSES }
+    scope :active, -> { where.not(status: TERMINAL) }
+
+    def terminal? = TERMINAL.include?(status)
+    def definition = workflow_definition.parsed
+
+    # Latest attempt per step key.
+    def current_steps
+      steps.group_by(&:step_key).transform_values { |list| list.max_by(&:attempt) }
+    end
+  end
+end

data/app/models/agentboard/workflow_step.rb

@@ -0,0 +1,12 @@
+module Agentboard
+  class WorkflowStep < ApplicationRecord
+    STATUSES = %w[pending running waiting succeeded failed skipped cancelled].freeze
+    TERMINAL = %w[succeeded failed skipped cancelled].freeze
+
+    belongs_to :workflow_run
+    has_many :executions, dependent: :nullify
+    validates :status, inclusion: { in: STATUSES }
+
+    def terminal? = TERMINAL.include?(status)
+  end
+end

data/app/services/agentboard/approvals.rb

@@ -0,0 +1,76 @@
+module Agentboard
+  # Approval requests bound to an exact action digest and code state (spec §28.5, AT-10).
+  module Approvals
+    DEFAULT_TTL = 72.hours
+
+    module_function
+
+    def request!(project:, action_kind:, actor:, action_payload: {}, reason: nil, ticket: nil, execution: nil,
+                 head_sha: nil, workflow_step: nil, required_role: "maintainer", ttl: DEFAULT_TTL, action_digest: nil)
+      Authorization.authorize!(actor, "approval.request")
+      digest = action_digest || Ids.canonical_digest(action_payload.to_h.merge(action_kind: action_kind, head_sha: head_sha, ticket_id: ticket&.id))
+      Approval.transaction do
+        existing = Approval.pending.find_by(project_id: project.id, ticket_id: ticket&.id, action_kind: action_kind, action_digest: digest)
+        return existing if existing && !existing.expired?
+
+        approval = Approval.create!(
+          project: project, ticket_id: ticket&.id, execution: execution, workflow_step_id: workflow_step&.id,
+          action_kind: action_kind, action_digest: digest, head_sha: head_sha, action_payload: Redactor.redact_value(action_payload.to_h),
+          reason: reason, required_role: required_role, requested_by: actor.label, expires_at: Time.current + ttl
+        )
+        EventStore.append!(type: "approval.requested", aggregate: approval, project: project, ticket: ticket, execution: execution, actor: actor,
+                           payload: { approval_id: approval.id, action_kind: action_kind, head_sha: head_sha, reason: reason })
+        approval
+      end
+    end
+
+    def request_review!(ticket:, actor:, head_sha:, summary: nil)
+      request!(project: ticket.project, ticket: ticket, actor: actor, action_kind: "review_completion", head_sha: head_sha,
+               action_digest: CompletionPolicy.review_action_digest(ticket, head_sha),
+               action_payload: { summary: summary.to_s.truncate(2000) }, reason: summary)
+    end
+
+    def decide!(approval:, actor:, decision:, reason: nil)
+      raise Error.forbidden("Only humans can decide approvals") unless actor.human?
+      Authorization.authorize!(actor, "approval.decide")
+      unless Authorization::ROLES.index(actor.role.to_s).to_i >= Authorization::ROLES.index(approval.required_role).to_i
+        raise Error.forbidden("Approval requires role #{approval.required_role}")
+      end
+      raise Error.validation_failed("Decision must be approved or rejected") unless %w[approved rejected].include?(decision)
+
+      Extensions.run(:before_approval_decision, approval: approval, actor: actor)
+
+      Approval.transaction do
+        approval.lock!
+        raise Error.invalid_transition("Approval is already #{approval.decision}") unless approval.pending?
+        if approval.expired?
+          approval.update!(decision: "expired")
+          raise Error.approval_required("Approval request expired; request a new one")
+        end
+        if approval.action_kind == "review_completion" && approval.ticket && approval.head_sha != Evidence.head_sha(approval.ticket)
+          approval.update!(decision: "invalidated", decision_reason: "head changed before decision")
+          raise Error.approval_required("Code changed since the review was requested; a new review is required")
+        end
+
+        approval.update!(decision: decision, decided_by: actor.label, decision_reason: reason, decided_at: Time.current)
+        EventStore.append!(type: "approval.#{decision}", aggregate: approval, project: approval.project, ticket: approval.ticket,
+                           actor: actor, payload: { approval_id: approval.id, action_kind: approval.action_kind, reason: reason })
+        approval
+      end
+    end
+
+    # Any relevant code change invalidates approvals bound to the old head (AT: "Agent edits code after approval").
+    def invalidate_stale!(ticket:, head_sha:)
+      stale = Approval.where(ticket_id: ticket.id, decision: %w[pending approved]).where.not(head_sha: [ nil, head_sha ])
+      stale.find_each do |approval|
+        approval.update!(decision: "invalidated", decision_reason: "head moved to #{head_sha.to_s[0, 10]}")
+        EventStore.append!(type: "approval.invalidated", aggregate: approval, project: approval.project, ticket: ticket,
+                           actor: Authorization.system_actor, payload: { approval_id: approval.id, new_head_sha: head_sha })
+      end
+    end
+
+    def expire_due!
+      Approval.pending.where("expires_at <= ?", Time.current).update_all(decision: "expired", updated_at: Time.current)
+    end
+  end
+end

data/app/services/agentboard/captures.rb

@@ -0,0 +1,113 @@
+module Agentboard
+  # Turns a capture from the in-app widget into a ticket plus a `capture` artifact (and an
+  # optional `screenshot` artifact). Everything coming from the browser is untrusted: it is
+  # bounded, validated and redacted before it is stored or shown to an agent.
+  module Captures
+    MAX_ELEMENTS = 10
+    MAX_SCREENSHOT_BYTES = 3 * 1024 * 1024
+    SAFE_PATH = %r{\A[\w./-]{1,300}\z}
+
+    module_function
+
+    def create!(project:, actor:, params:)
+      Authorization.authorize!(actor, "ticket.write")
+      p = params.to_h.deep_stringify_keys
+      title = p["title"].to_s.strip[0, 200]
+      raise Error.validation_failed("A title is required") if title.blank?
+
+      kind = p["kind"].to_s.presence_in(Ticket::KINDS) || "bug"
+      priority = p["priority"].to_i.clamp(0, 3)
+      url = sanitize_url(p["url"])
+      elements = Array(p["elements"]).first(MAX_ELEMENTS).map { |e| sanitize_element(e) }
+      templates = Array(p["templates"]).map(&:to_s).select { |t| safe_path?(t) }.uniq.first(50)
+      console = Array(p["console_errors"]).first(20).map { |c| Redactor.redact(c.to_s)[0, 500] }
+      meta = {
+        "url" => url, "route" => p["route"].to_s[0, 120].presence, "viewport" => sanitize_viewport(p["viewport"]),
+        "user_agent" => p["user_agent"].to_s[0, 300], "elements" => elements, "templates" => templates,
+        "console_errors" => console, "captured_by" => actor.label
+      }
+      expected = p["expected"].to_s.strip[0, 500]
+      ticket = nil
+      Ticket.transaction do
+        ticket = Tickets.create!(project: project, actor: actor, title: title, kind: kind, priority: priority,
+                                 description: description_for(p["description"], meta), labels: [ "captured" ],
+                                 criteria: expected.present? ? [ expected ] : [], status: expected.present? ? "ready" : "backlog")
+        Artifact.create!(ticket: ticket, kind: "capture", uri: url.presence || "capture:#{ticket.key}", title: "Captured from #{meta["route"] || url}",
+                         provenance: "confirmed", metadata: meta)
+        attach_screenshot!(ticket, p["screenshot"]) if p["screenshot"].present?
+        EventStore.append!(type: "ticket.captured", aggregate: ticket, ticket: ticket, actor: actor,
+                           payload: { url: url, route: meta["route"], elements: elements.size, templates: templates.size })
+      end
+      ticket
+    end
+
+    def safe_path?(path) = path.match?(SAFE_PATH) && PathGuard.safe_relative?(path)
+
+    def sanitize_url(value)
+      uri = URI.parse(value.to_s)
+      return nil unless %w[http https].include?(uri.scheme)
+
+      # Query strings often carry tokens; keep only the path for traceability.
+      "#{uri.scheme}://#{uri.host}#{":#{uri.port}" if uri.port && ![ 80, 443 ].include?(uri.port)}#{uri.path}"[0, 500]
+    rescue URI::InvalidURIError
+      nil
+    end
+
+    def sanitize_viewport(v)
+      v = v.is_a?(Hash) ? v.transform_keys(&:to_s) : {}
+      { "width" => v["width"].to_i.clamp(0, 10_000), "height" => v["height"].to_i.clamp(0, 10_000) }
+    end
+
+    def sanitize_element(e)
+      e = e.is_a?(Hash) ? e.transform_keys(&:to_s) : {}
+      rect = e["rect"].is_a?(Hash) ? e["rect"].transform_keys(&:to_s).slice("x", "y", "width", "height").transform_values { |n| n.to_f.round(1) } : {}
+      template = e["template"].to_s
+      {
+        "selector" => e["selector"].to_s[0, 500], "text" => Redactor.redact(e["text"].to_s.squish[0, 300]),
+        "html" => Redactor.redact(e["html"].to_s[0, 4000]), "template" => safe_path?(template) ? template : nil, "rect" => rect
+      }.compact
+    end
+
+    def description_for(text, meta)
+      parts = [ Redactor.redact(text.to_s.strip[0, 10_000]).presence ]
+      parts << "### Captured from\n- Page: #{meta["url"] || "unknown"}\n- Route: `#{meta["route"] || "unknown"}`\n" \
+               "- Viewport: #{meta.dig("viewport", "width")}×#{meta.dig("viewport", "height")}"
+      if meta["elements"].any?
+        parts << "### Selected elements\n" + meta["elements"].map.with_index(1) do |el, i|
+          line = "#{i}. `#{el["selector"]}`"
+          line += " — rendered by `#{el["template"]}`" if el["template"]
+          line += "\n   “#{el["text"].truncate(160)}”" if el["text"].present?
+          line
+        end.join("\n")
+      end
+      parts << "### Templates rendered on this page\n" + meta["templates"].first(20).map { |t| "- `#{t}`" }.join("\n") if meta["templates"].any?
+      parts << "### Console errors\n" + meta["console_errors"].map { |c| "- #{c}" }.join("\n") if meta["console_errors"].any?
+      parts.compact.join("\n\n")
+    end
+
+    def attach_screenshot!(ticket, data_url)
+      Agentboard.require_feature!(:capture)
+      match = data_url.to_s.match(%r{\Adata:image/png;base64,([A-Za-z0-9+/=]+)\z})
+      raise Error.validation_failed("Screenshot must be a PNG data URL") unless match
+
+      bytes = Base64.strict_decode64(match[1])
+      raise Error.validation_failed("Screenshot is too large") if bytes.bytesize > MAX_SCREENSHOT_BYTES
+      raise Error.validation_failed("Screenshot is not a PNG") unless bytes.start_with?("\x89PNG".b)
+
+      dir = Agentboard.config.root_path.join(".agentboard", "captures")
+      FileUtils.mkdir_p(dir, mode: 0o700)
+      path = dir.join("#{ticket.key}-#{SecureRandom.hex(4)}.png")
+      File.binwrite(path, bytes)
+      File.chmod(0o600, path)
+      Artifact.create!(ticket: ticket, kind: "screenshot", uri: "file:#{path}", title: "Screenshot of the selected area",
+                       sha256: Digest::SHA256.hexdigest(bytes), provenance: "confirmed", metadata: { "bytes" => bytes.bytesize })
+    end
+
+    # Paths an agent should look at first for a captured ticket.
+    def focus_paths(ticket)
+      ticket.artifacts.where(kind: "capture").flat_map do |a|
+        Array(a.metadata["elements"]).filter_map { |e| e["template"] } + Array(a.metadata["templates"])
+      end.uniq.first(20)
+    end
+  end
+end

data/app/services/agentboard/completion_policy.rb

@@ -0,0 +1,117 @@
+module Agentboard
+  # Evidence-based completion (spec §15, §29.4). Agents may *request* completion but every
+  # gate is evaluated against persisted records — never against agent-supplied JSON.
+  module CompletionPolicy
+    module_function
+
+    def settings = Agentboard.config.completion
+
+    # require_merged_pr: "when_linked" (default) | "always" | "never" (true/false accepted).
+    # "when_linked": a ticket with an open or merged PR must have that PR merged on the
+    # reviewed head; tickets without a PR (or only abandoned ones) complete on other evidence.
+    def merged_pr_mode
+      case settings["require_merged_pr"]
+      when true, "always" then "always"
+      when false, nil, "never" then "never"
+      else "when_linked"
+      end
+    end
+
+    def merged_pr_required?(ticket)
+      case merged_pr_mode
+      when "always" then true
+      when "never" then false
+      else ticket.artifacts.where(kind: "pull_request").any? { |a| %w[open merged].include?(a.metadata["state"]) }
+      end
+    end
+
+    # Required checks must have passed for exactly `head_sha` (AT-08).
+    def checks_report(ticket, head_sha:)
+      missing = []
+      required = Agentboard.config.verification_catalog.required_names
+      if head_sha.blank?
+        missing << "no verified head commit is linked to the ticket"
+        return { ok: false, head_sha: nil, missing: missing, checks: [] }
+      end
+
+      checks = required.map do |name|
+        result = VerificationResult.where(ticket_id: ticket.id, name: name).order(started_at: :desc).first
+        latest_for_head = VerificationResult.where(ticket_id: ticket.id, name: name, commit_sha: head_sha).order(started_at: :desc).first
+        status =
+          if latest_for_head&.passed? then "passed"
+          elsif latest_for_head then latest_for_head.status
+          elsif result then "stale"
+          else "missing"
+          end
+        missing << "#{name} #{status == "stale" ? "passed only for an older commit" : status} at #{head_sha[0, 10]}" unless status == "passed"
+        { name: name, status: status, commit_sha: latest_for_head&.commit_sha || result&.commit_sha, result_id: latest_for_head&.id }
+      end
+      { ok: missing.empty?, head_sha: head_sha, missing: missing, checks: checks }
+    end
+
+    def review_action_digest(ticket, head_sha)
+      Ids.canonical_digest(action: "review_completion", ticket_id: ticket.id, head_sha: head_sha)
+    end
+
+    def evaluate(ticket, actor: nil)
+      head = Evidence.head_sha(ticket)
+      missing = []
+      report = { ticket_key: ticket.key, head_sha: head }
+
+      if settings["require_criteria_verified"]
+        crit = ticket.acceptance_criteria.map { |c| { id: c.id, status: c.state, evidence_id: c.evidence_id } }
+        unsatisfied = ticket.acceptance_criteria.reject(&:satisfied?)
+        missing << "#{unsatisfied.size} acceptance criteria not verified" if unsatisfied.any?
+        missing << "ticket has no acceptance criteria" if crit.empty?
+        report[:criteria] = crit
+      end
+
+      if settings["require_checks"]
+        checks = checks_report(ticket, head_sha: head)
+        missing.concat(checks[:missing])
+        report[:required_checks] = checks[:checks]
+      end
+
+      if settings["require_approval"] || Agentboard.config.security["require_review"]
+        digest = head && review_action_digest(ticket, head)
+        approval = head && Approval.where(ticket_id: ticket.id, action_kind: "review_completion", decision: "approved").order(decided_at: :desc)
+                                   .find { |a| a.valid_for?(action_digest: digest, head_sha: head) }
+        missing << "human review approval for #{head ? head[0, 10] : "the current head"} is missing" unless approval
+        report[:review] = approval ? { status: "approved", approval_id: approval.id } : { status: "pending" }
+      end
+
+      if merged_pr_required?(ticket)
+        # The merged PR must carry exactly the head that passed checks and review.
+        pr = ticket.artifacts.where(kind: "pull_request").find do |a|
+          a.metadata["state"] == "merged" && a.metadata["merge_verified"] && head.present? && a.metadata["head_sha"] == head
+        end
+        missing << "merged pull request (verified by the Git provider) for #{head ? head[0, 10] : "the current head"}" unless pr
+        report[:pull_request] = pr ? { state: "merged", merge_commit_sha: pr.metadata["merge_commit_sha"] } : { state: "missing" }
+      end
+
+      report.merge(ok: missing.empty?, missing: missing)
+    end
+
+    # Policy-controlled completion used by the UI and the MCP `complete_ticket` tool.
+    def complete!(ticket:, actor:, expected_version: nil, lease_token: nil, session: nil)
+      report = evaluate(ticket, actor: actor)
+      raise Error.policy_denied("Completion policy not satisfied", missing: report[:missing]) unless report[:ok]
+
+      if actor.agent?
+        # Agents need a valid lease; the human approval gate above has already been met.
+        LeaseService.validate!(ticket: ticket, token: lease_token, session: session)
+        ticket.transaction do
+          ticket.lock!
+          StateMachines::Ticket.assert!(ticket.status, "done")
+          ticket.update!(status: "done", completed_at: Time.current)
+          LeaseService.release_all!(ticket: ticket, reason: "ticket_done")
+          EventStore.append!(type: "ticket.transitioned", aggregate: ticket, ticket: ticket, actor: actor, session: session,
+                             payload: { from: "review", to: "done", evidence: report.except(:missing, :ok) })
+        end
+        ticket
+      else
+        Tickets.transition!(ticket: ticket, to: "done", actor: actor, expected_version: expected_version)
+      end
+    end
+  end
+end

data/app/services/agentboard/current.rb

@@ -0,0 +1,5 @@
+module Agentboard
+  class Current < ActiveSupport::CurrentAttributes
+    attribute :correlation_id, :actor
+  end
+end

data/app/services/agentboard/data_governance.rb

@@ -0,0 +1,68 @@
+module Agentboard
+  # Retention and deletion (spec §32.3). Ticket and audit metadata are kept; raw logs,
+  # provider output events, delivered outbox rows and expired idempotency keys age out.
+  # Purging a project is a separate, explicitly confirmed operation.
+  module DataGovernance
+    PROVIDER_OUTPUT_EVENTS = %w[agent.execution.output agent.execution.message agent.provider.unknown agent.provider.system].freeze
+
+    module_function
+
+    def apply_retention!(project:, dry_run: false, now: Time.current)
+      r = Agentboard.config.settings["retention"] || {}
+      log_cutoff = now - r.fetch("raw_log_days", 30).to_i.days
+      event_cutoff = now - r.fetch("provider_output_event_days", 30).to_i.days
+      logs_root = Agentboard.config.root_path.join(".agentboard", "logs")
+      old_logs = Dir[logs_root.join("*").to_s].select { |d| File.mtime(d) < log_cutoff }
+      events = Event.where(project_id: project.id, event_type: PROVIDER_OUTPUT_EVENTS).where("received_at < ?", event_cutoff)
+      outbox = OutboxMessage.where(state: "delivered").where("delivered_at < ?", now - 7.days)
+      keys = IdempotencyKey.where("expires_at < ?", now)
+      deliveries = WebhookDelivery.where("created_at < ?", now - 90.days)
+      report = { log_dirs: old_logs.size, provider_output_events: events.count, delivered_outbox: outbox.count,
+                 idempotency_keys: keys.count, webhook_deliveries: deliveries.count, dry_run: dry_run }
+      return report if dry_run
+
+      FileUtils.rm_rf(old_logs)
+      OutboxMessage.where(event_id: events.select(:id)).delete_all
+      events.delete_all
+      outbox.delete_all
+      keys.delete_all
+      deliveries.delete_all
+      EventStore.append!(type: "security.retention_applied", aggregate: project, project: project, actor: Authorization.system_actor,
+                         payload: report.except(:dry_run))
+      report
+    end
+
+    # Deletes every AgentBoard record of a project. Requires typing the project key.
+    def purge_project!(project:, confirm:, actor:)
+      raise Error.forbidden("Only administrators can purge") unless actor.role == "administrator"
+      raise Error.validation_failed("Confirmation must equal the project key (#{project.key})") unless confirm.to_s == project.key
+
+      counts = {}
+      ActiveRecord::Base.transaction do
+        tickets = Ticket.where(project_id: project.id)
+        executions = Execution.where(ticket_id: tickets.select(:id))
+        runs = WorkflowRun.where(ticket_id: tickets.select(:id))
+        steps = WorkflowStep.where(workflow_run_id: runs.select(:id))
+        sessions = AgentSession.where(project_id: project.id)
+        events = Event.where(project_id: project.id)
+        {
+          outbox: OutboxMessage.where(event_id: events.select(:id)), events: events,
+          usage: UsageRecord.where(execution_id: executions.select(:id)), verification: VerificationResult.where(execution_id: executions.select(:id)),
+          approvals: Approval.where(project_id: project.id), artifacts: Artifact.where(ticket_id: tickets.select(:id)),
+          executions: executions, steps: steps, runs: runs, workflows: WorkflowDefinition.where(project_id: project.id),
+          leases: TicketLease.where(ticket_id: tickets.select(:id)), links: SessionTicketLink.where(agent_session_id: sessions.select(:id)),
+          sessions: sessions, profiles: AgentProfile.where(project_id: project.id), comments: Comment.where(ticket_id: tickets.select(:id)),
+          criteria: AcceptanceCriterion.where(ticket_id: tickets.select(:id)),
+          dependencies: TicketDependency.where(ticket_id: tickets.select(:id)).or(TicketDependency.where(depends_on_ticket_id: tickets.select(:id))),
+          snapshots: RepositorySnapshot.where(project_id: project.id)
+        }.each { |name, scope| counts[name] = scope.delete_all }
+        tickets.update_all(parent_id: nil)
+        counts[:tickets] = tickets.delete_all
+        counts[:milestones] = Milestone.where(project_id: project.id).delete_all
+        project.delete
+      end
+      Agentboard.logger.warn("[agentboard] project #{project.key} purged by #{actor.label}: #{counts}")
+      counts
+    end
+  end
+end