planka-cli 0.1.0

data/test/lib/planka/blocker_test.rb

@@ -0,0 +1,51 @@
+require_relative "planka_test_helper"
+
+class Planka::BlockerTest < Minitest::Test
+  Card = Struct.new(:name) do
+    def to_s = "#{name} (https://planka.example/cards/1)"
+  end
+
+  def blocker(name, branch: nil, state: nil, head: branch)
+    handoff = Planka::Handoff.new(branch:, pr_url: state && "https://github.com/x/y/pull/#{name}") if branch
+    pr = Planka::PullRequest.new(state:, head:) if state
+    Planka::Blocker.new(card: Card.new(name), handoff:, pr:)
+  end
+
+  def parent(*blockers) = Planka::Blocker.parent_branch(blockers)
+
+  def test_no_blockers_stack_on_main
+    assert_equal "main", parent
+  end
+
+  def test_merged_blockers_stack_on_main
+    assert_equal "main", parent(blocker("1", branch: "plan-3/01", state: "MERGED"))
+  end
+
+  def test_one_open_blocker_stacks_on_its_branch
+    assert_equal "plan-3/05", parent(blocker("4", branch: "plan-3/04", state: "MERGED"), blocker("5", branch: "plan-3/05", state: "OPEN"))
+  end
+
+  def test_the_pr_head_wins_over_the_recorded_branch
+    assert_equal "plan-3/05-renamed", parent(blocker("5", branch: "plan-3/05", state: "OPEN", head: "plan-3/05-renamed"))
+  end
+
+  def test_a_blocker_without_a_pr_counts_as_unmerged
+    assert_equal "plan-3/05", parent(blocker("5", branch: "plan-3/05"))
+  end
+
+  def test_two_open_blockers_are_ambiguous
+    result = parent(blocker("5", branch: "plan-3/05", state: "OPEN"), blocker("6", branch: "plan-3/06", state: "OPEN"))
+
+    assert_equal "AMBIGUOUS: unmerged blockers plan-3/05, plan-3/06", result
+  end
+
+  def test_a_blocker_without_a_handoff_comment_is_ambiguous
+    assert_equal "AMBIGUOUS: no Branch: comment on 5", parent(blocker("5"))
+  end
+
+  def test_describes_itself_for_the_report
+    assert_equal "- 5 (https://planka.example/cards/1): branch plan-3/05, PR https://github.com/x/y/pull/5 (open)",
+      blocker("5", branch: "plan-3/05", state: "OPEN").to_s
+    assert_equal "- 5 (https://planka.example/cards/1): no Branch: comment", blocker("5").to_s
+  end
+end

data/test/lib/planka/blocking_test.rb

@@ -0,0 +1,76 @@
+require_relative "planka_test_helper"
+
+class Planka::BlockingTest < Minitest::Test
+  # Stands in for Planka::Client: serves one card's task lists and tasks, and
+  # records the writes Blocking asks for.
+  class FakeClient
+    attr_reader :writes
+
+    def initialize(task_lists: [], tasks: [])
+      @task_lists = task_lists
+      @tasks = tasks
+      @writes = []
+    end
+
+    def card(_id) = { "included" => { "taskLists" => @task_lists, "tasks" => @tasks } }
+
+    def create_task_list(card_id, **attrs)
+      @writes << [ :create_task_list, card_id, attrs ]
+      { "id" => "new-list", "name" => attrs[:name], "position" => attrs[:position] }
+    end
+
+    def create_task(task_list_id, **attrs)
+      @writes << [ :create_task, task_list_id, attrs ]
+      { "id" => "task-#{@writes.size}", "isCompleted" => attrs[:linkedCardId] == "closed-card" }.merge(attrs.transform_keys(&:to_s))
+    end
+  end
+
+  def link(client, blockers) = Planka::Blocking.new(client).link("10", blockers)
+
+  def test_creates_the_blocked_by_list_after_existing_lists
+    client = FakeClient.new(task_lists: [ { "id" => "ac", "name" => "Acceptance criteria", "position" => 65_536 } ])
+
+    link(client, [ "1" ])
+
+    assert_equal [ :create_task_list, "10", { name: "Blocked by", position: 131_072, showOnFrontOfCard: true } ], client.writes.first
+  end
+
+  def test_links_each_blocker_once_in_order
+    client = FakeClient.new
+
+    assert_equal [ "linked: 1 (open)", "linked: 2 (open)" ], link(client, [ "1", "2", "1" ])
+    assert_equal [ [ :create_task, "new-list", { linkedCardId: "1", position: 65_536 } ],
+                   [ :create_task, "new-list", { linkedCardId: "2", position: 131_072 } ] ], client.writes.drop(1)
+  end
+
+  def test_reuses_the_existing_list_and_skips_blockers_already_linked
+    client = FakeClient.new(
+      task_lists: [ { "id" => "bb", "name" => "Blocked by", "position" => 65_536 } ],
+      tasks: [ { "id" => "t1", "taskListId" => "bb", "linkedCardId" => "1", "position" => 65_536 } ]
+    )
+
+    assert_equal [ "already linked: 1", "linked: 2 (open)" ], link(client, [ "1", "2" ])
+    assert_equal [ [ :create_task, "bb", { linkedCardId: "2", position: 131_072 } ] ], client.writes
+  end
+
+  def test_reports_a_blocker_that_is_already_closed
+    assert_equal [ "linked: closed-card (closed)" ], link(FakeClient.new, [ "closed-card" ])
+  end
+
+  def test_a_card_cannot_block_itself
+    error = assert_raises(Planka::Error) { link(FakeClient.new, [ "10" ]) }
+
+    assert_equal "a card cannot block itself", error.message
+  end
+
+  def test_card_id_accepts_ids_and_card_urls
+    assert_equal "1870510968568546410", Planka.card_id("1870510968568546410")
+    assert_equal "1870510968568546410", Planka.card_id("http://planka.test:3000/cards/1870510968568546410/")
+  end
+
+  def test_card_id_rejects_anything_else
+    error = assert_raises(Planka::Error) { Planka.card_id("Contract edits") }
+
+    assert_equal "not a card id or URL: Contract edits", error.message
+  end
+end

data/test/lib/planka/board_test.rb

@@ -0,0 +1,77 @@
+require_relative "planka_test_helper"
+
+class Planka::BoardTest < Minitest::Test
+  include PlankaTestHelper
+
+  def test_cards_labelled_returns_the_cards_carrying_the_label
+    names = board.cards_labelled("feature:workspaces").map(&:name)
+
+    assert_equal 10, names.size
+    assert_includes names, "Spec: Workspaces, membership and roles (Plan 3)"
+  end
+
+  def test_cards_labelled_raises_for_an_unknown_label
+    error = assert_raises(Planka::Error) { board.cards_labelled("feature:nope") }
+
+    assert_equal "no label feature:nope", error.message
+  end
+
+  def test_a_ticket_has_acceptance_criteria_and_the_spec_does_not
+    assert board.card(card_id("Contract edits")).ticket?
+    refute board.card(card_id("Spec:")).ticket?
+  end
+
+  def test_the_first_ticket_is_takeable
+    assert board.card(card_id("Contract edits")).takeable?
+  end
+
+  def test_a_ticket_with_an_open_blocker_is_not_takeable
+    card = board.card(card_id("Create a workspace"))
+
+    refute card.takeable?
+    assert_equal [ "Contract edits" ], card.open_blockers.map { |b| b.name[0, 14] }
+  end
+
+  def test_closing_the_blocker_makes_the_ticket_takeable
+    close(card_id("Contract edits"))
+
+    assert board.card(card_id("Create a workspace")).takeable?
+  end
+
+  def test_a_claimed_card_is_not_takeable
+    claim(card_id("Contract edits"))
+    card = board.card(card_id("Contract edits"))
+
+    assert card.claimed?
+    refute card.takeable?
+  end
+
+  def test_a_card_outside_ready_for_agent_is_not_takeable
+    move(card_id("Contract edits"), "in-progress")
+
+    refute board.card(card_id("Contract edits")).takeable?
+  end
+
+  def test_blockers_lists_every_linked_card_whether_open_or_closed
+    id = card_id("Adding members")
+    close(card_id("Documents inside"))
+
+    assert_equal [ card_id("Documents inside") ], board.card(id).blockers.map(&:id)
+    assert_empty board.card(id).open_blockers
+  end
+
+  def test_a_card_renders_as_its_name_and_link
+    assert_equal "Transferring ownership (http://planka.test:3000/cards/#{card_id("Transferring")})",
+      board.card(card_id("Transferring")).to_s
+  end
+
+  def test_unticked_criteria_are_the_open_tasks_in_the_acceptance_criteria_list
+    card = card_id("Contract edits")
+    criteria = payload["taskLists"].find { |tl| tl["cardId"] == card && tl["name"] == "Acceptance criteria" }.fetch("id")
+    tasks = payload["tasks"].select { |t| t["taskListId"] == criteria }
+    tasks.first["isCompleted"] = true
+
+    assert_equal tasks.drop(1).map { |t| t["name"] }, board.card(card).unticked_criteria
+    refute_empty board.card(card).unticked_criteria
+  end
+end

data/test/lib/planka/branch_name_test.rb

@@ -0,0 +1,36 @@
+require_relative "planka_test_helper"
+
+class Planka::BranchNameTest < Minitest::Test
+  include PlankaTestHelper
+
+  def branch(name, features: [])
+    card = Struct.new(:name, :features).new(name, features)
+    Planka::BranchName.for(card)
+  end
+
+  def test_a_feature_ticket_names_its_feature_number_and_title
+    assert_equal "feature/tracer-1.1-a-monitor-sees-lucenta-is-up",
+      branch("1.1 A monitor sees lucenta is up", features: [ "feature:tracer" ])
+  end
+
+  def test_punctuation_becomes_single_hyphens
+    assert_equal "feature/work-next-w2-the-top-of-ready-for-agent-is-the",
+      branch("W2 The top of ready-for-agent is the priority!", features: [ "feature:work-next" ])
+  end
+
+  def test_a_card_without_a_feature_is_named_by_its_title
+    assert_equal "card/fix-the-login-redirect", branch("Fix the login redirect")
+  end
+
+  def test_the_name_fits_a_dns_label_after_the_lucenta_prefix_and_ends_on_a_whole_word
+    name = branch("1.2 An account signs in; the first admin exists", features: [ "feature:tracer" ])
+
+    assert_equal "feature/tracer-1.2-an-account-signs-in-the-first-admin", name
+    assert_operator "lucenta-#{name}".length, :<=, 63
+  end
+
+  def test_a_fixture_card_takes_its_feature_from_its_labels
+    assert_equal "feature/workspaces-contract-edits-by-direct-request",
+      Planka::BranchName.for(board.card(card_id("Contract edits")))
+  end
+end

data/test/lib/planka/configuration_test.rb

@@ -0,0 +1,83 @@
+require_relative "planka_test_helper"
+require_relative "../../../lib/planka/client"
+require "tmpdir"
+
+class Planka::ConfigurationTest < Minitest::Test
+  def with_configuration(env = {})
+    previous = ENV.to_h
+    ENV.keys.grep(/\APLANKA_/).each { |key| ENV.delete(key) }
+    ENV.update(env)
+    Dir.mktmpdir("planka-config") do |directory|
+      Dir.chdir(directory) { yield directory }
+    end
+  ensure
+    ENV.replace(previous)
+  end
+
+  def write_config(path, env)
+    File.write(path, JSON.generate("mcpServers" => { "planka" => { "env" => env } }))
+  end
+
+  def test_default_mcp_configuration_belongs_to_the_caller
+    with_configuration do
+      write_config(".mcp.json", "PLANKA_BOARD_ID" => "caller-board", "PLANKA_BASE_URL" => "http://localhost:3000/")
+      Planka::Client.configure!
+
+      assert_equal "caller-board", Planka.board_id
+      assert_equal "http://localhost:3000/cards/123", Planka.card_url("123")
+    end
+  end
+
+  def test_custom_mcp_path_is_relative_to_the_caller
+    with_configuration("PLANKA_MCP_CONFIG" => "workflow/mcp.json") do
+      Dir.mkdir("workflow")
+      write_config("workflow/mcp.json", "PLANKA_BOARD_ID" => "workflow-board")
+      Planka::Client.configure!
+
+      assert_equal "workflow-board", Planka.board_id
+    end
+  end
+
+  def test_explicit_environment_overrides_mcp_settings
+    with_configuration("PLANKA_BOARD_ID" => "explicit-board", "PLANKA_AGENT_PASSWORD" => "plain-password") do
+      write_config(".mcp.json", "PLANKA_BOARD_ID" => "mcp-board", "PLANKA_AGENT_PASSWORD" => "op://vault/agent/password",
+        "PLANKA_AGENT_EMAIL" => "agent@example.test")
+      Planka::Client.configure!
+
+      assert_equal "explicit-board", Planka.board_id
+      assert_equal "plain-password", ENV.fetch("PLANKA_AGENT_PASSWORD")
+      assert_equal "agent@example.test", ENV.fetch("PLANKA_AGENT_EMAIL")
+    end
+  end
+
+  def test_explicit_missing_configuration_is_an_error
+    with_configuration("PLANKA_MCP_CONFIG" => "missing.json") do
+      assert_raises(Errno::ENOENT) { Planka::Client.configure! }
+    end
+  end
+
+  def test_missing_board_configuration_is_not_replaced_with_an_instance_default
+    with_configuration do
+      Planka::Client.configure!
+
+      error = assert_raises(KeyError) { Planka.board_id }
+      assert_equal "PLANKA_BOARD_ID", error.key
+    end
+  end
+
+  def test_missing_credentials_are_reported_without_a_configuration_file
+    with_configuration("PLANKA_BASE_URL" => "http://localhost:3000", "PLANKA_AGENT_EMAIL" => "agent@example.test") do
+      error = assert_raises(KeyError) { Planka::Client.resolve_credentials!(__FILE__, []) }
+
+      assert_equal "PLANKA_AGENT_PASSWORD", error.key
+    end
+  end
+
+  def test_card_urls_follow_the_current_base_url
+    with_configuration("PLANKA_BASE_URL" => "http://localhost:3000") do
+      assert_equal "http://localhost:3000/cards/123", Planka.card_url("123")
+      ENV["PLANKA_BASE_URL"] = "https://planka.example/"
+      assert_equal "https://planka.example/cards/456", Planka.card_url("456")
+    end
+  end
+end

data/test/lib/planka/handoff_test.rb

@@ -0,0 +1,45 @@
+require_relative "planka_test_helper"
+
+class Planka::HandoffTest < Minitest::Test
+  def test_parses_plain_lines
+    handoff = Planka::Handoff.parse("Branch: plan-3/01-contract-edits\nPR: https://github.com/marshally/markdocs/pull/8")
+
+    assert_equal "plan-3/01-contract-edits", handoff.branch
+    assert_equal "https://github.com/marshally/markdocs/pull/8", handoff.pr_url
+  end
+
+  def test_parses_markdown_decoration
+    handoff = Planka::Handoff.parse("Branch: `plan-3/01-contract-edits`\nPR: <https://github.com/marshally/markdocs/pull/8>.")
+
+    assert_equal "plan-3/01-contract-edits", handoff.branch
+    assert_equal "https://github.com/marshally/markdocs/pull/8", handoff.pr_url
+  end
+
+  def test_finds_the_lines_among_other_text
+    handoff = Planka::Handoff.parse("Opened the PR.\n\nBranch: plan-3/02-create\nPR: https://github.com/x/y/pull/9\n\nAll criteria ticked.")
+
+    assert_equal "plan-3/02-create", handoff.branch
+  end
+
+  def test_a_branch_without_a_pr_line
+    assert_nil Planka::Handoff.parse("Branch: plan-3/02-create").pr_url
+  end
+
+  def test_text_without_a_branch_line_is_not_a_handoff
+    assert_nil Planka::Handoff.parse("Claimed; starting on the migration.")
+  end
+
+  def test_latest_takes_the_newest_handoff_comment
+    comments = [
+      { "createdAt" => "2026-09-24T10:00:00Z", "text" => "Branch: old\nPR: https://github.com/x/y/pull/1" },
+      { "createdAt" => "2026-09-25T10:00:00Z", "text" => "Branch: new\nPR: https://github.com/x/y/pull/2" },
+      { "createdAt" => "2026-09-26T10:00:00Z", "text" => "Moved to done." }
+    ]
+
+    assert_equal "new", Planka::Handoff.latest(comments).branch
+  end
+
+  def test_latest_is_nil_without_a_handoff_comment
+    assert_nil Planka::Handoff.latest([ { "createdAt" => "2026-09-24T10:00:00Z", "text" => "Claimed." } ])
+  end
+end

data/test/lib/planka/loop_lock_test.rb

@@ -0,0 +1,49 @@
+require_relative "planka_test_helper"
+
+class Planka::LoopLockTest < Minitest::Test
+  include PlankaTestHelper
+
+  BOT = "bot"
+
+  Comments = Struct.new(:by_card) do
+    def comments(card_id) = by_card.fetch(card_id, [])
+  end
+
+  def held(comments: {}) = Planka::LoopLock.held(boards: [ board ], user_id: BOT, comments: Comments.new(comments))
+
+  def claim_as_bot(id) = payload["cardMemberships"] << { "cardId" => id, "userId" => BOT }
+
+  def handoff = [ { "createdAt" => "2026-09-29T10:00:00Z", "text" => "Branch: b\nPR: https://github.com/x/y/pull/1" } ]
+
+  def test_nothing_claimed_by_the_bot_is_free
+    claim(card_id("Contract edits"))
+
+    assert_nil held
+  end
+
+  def test_a_bot_claim_without_a_pr_holds_the_lock
+    claim_as_bot(card_id("Contract edits"))
+    move(card_id("Contract edits"), "in-progress")
+
+    assert_equal card_id("Contract edits"), held.id
+  end
+
+  def test_a_bot_claim_whose_pr_is_handed_off_does_not
+    claim_as_bot(card_id("Contract edits"))
+
+    assert_nil held(comments: { card_id("Contract edits") => handoff })
+  end
+
+  def test_a_closed_bot_claim_does_not
+    claim_as_bot(card_id("Contract edits"))
+    close(card_id("Contract edits"))
+
+    assert_nil held
+  end
+
+  def test_the_card_knows_when_the_bot_claimed_it
+    payload["cardMemberships"] << { "cardId" => card_id("Contract edits"), "userId" => BOT, "createdAt" => "2026-09-29T15:00:00.000Z" }
+
+    assert_equal Time.utc(2026, 9, 29, 15), held.claimed_at(BOT)
+  end
+end

data/test/lib/planka/next_card_test.rb

@@ -0,0 +1,158 @@
+require_relative "planka_test_helper"
+
+class Planka::NextCardTest < Minitest::Test
+  include PlankaTestHelper
+
+  Comments = Struct.new(:by_card) do
+    def comments(card_id) = by_card.fetch(card_id, [])
+  end
+
+  PullRequests = Struct.new(:by_url) do
+    def find(url) = by_url[url]
+  end
+
+  def next_card(label, comments: {}, prs: {})
+    Planka::NextCard.for(label, board:, comments: Comments.new(comments), pull_requests: PullRequests.new(prs)).to_s
+  end
+
+  def handoff(branch, pr) = [ { "createdAt" => "2026-09-24T10:00:00Z", "text" => "Branch: #{branch}\nPR: #{pr}" } ]
+
+  def pr(state, head) = Planka::PullRequest.new(state:, head:)
+
+  def line(prefix) = board.card(card_id(prefix)).to_s
+
+  def test_a_fresh_feature_picks_the_first_ticket_on_main
+    assert_equal <<~REPORT.chomp, next_card("feature:workspaces")
+      card: #{line("Contract edits")}
+      spec: #{line("Spec:")}
+      nn: 01
+      blockers: none
+      parent: main
+    REPORT
+  end
+
+  def test_an_open_blocker_pr_stacks_on_its_branch
+    close(card_id("Contract edits"))
+    report = next_card("feature:workspaces",
+      comments: { card_id("Contract edits") => handoff("plan-3/01-contract-edits", "https://github.com/x/y/pull/8") },
+      prs: { "https://github.com/x/y/pull/8" => pr("OPEN", "plan-3/01-contract-edits") })
+
+    assert_equal <<~REPORT.chomp, report
+      card: #{line("Create a workspace")}
+      spec: #{line("Spec:")}
+      nn: 02
+      blockers:
+      - #{line("Contract edits")}: branch plan-3/01-contract-edits, PR https://github.com/x/y/pull/8 (open)
+      parent: plan-3/01-contract-edits
+    REPORT
+  end
+
+  def test_a_merged_blocker_pr_stacks_on_main
+    close(card_id("Contract edits"))
+    report = next_card("feature:workspaces",
+      comments: { card_id("Contract edits") => handoff("plan-3/01-contract-edits", "https://github.com/x/y/pull/8") },
+      prs: { "https://github.com/x/y/pull/8" => pr("MERGED", "plan-3/01-contract-edits") })
+
+    assert_equal "parent: main", report.lines.last
+  end
+
+  def test_a_blocker_without_a_handoff_comment_is_ambiguous
+    close(card_id("Contract edits"))
+
+    assert_match(/^parent: AMBIGUOUS: no Branch: comment on Contract edits/, next_card("feature:workspaces"))
+  end
+
+  def test_ticket_order_follows_creation_not_position
+    close(*ticket_ids.first(5))
+    report = next_card("feature:workspaces",
+      comments: { card_id("Documents inside") => handoff("plan-3/05-documents", "https://github.com/x/y/pull/12") },
+      prs: { "https://github.com/x/y/pull/12" => pr("OPEN", "plan-3/05-documents") })
+
+    assert_match(/^card: Adding members/, report)
+    assert_match(/^nn: 06$/, report)
+    assert_equal "parent: plan-3/05-documents", report.lines.last
+  end
+
+  def test_nothing_takeable_lists_what_holds_each_waiting_ticket
+    claim(card_id("Contract edits"))
+    report = next_card("feature:workspaces").lines(chomp: true)
+
+    assert_equal "none:", report[0]
+    assert_equal "- #{line("Contract edits")}: claimed", report[1]
+    assert_equal "- #{line("Create a workspace")}: blocked by #{board.card(card_id("Contract edits")).name}", report[2]
+    assert_equal 10, report.size
+  end
+
+  def position(id, value) = payload["cards"].find { |c| c["id"] == id }["position"] = value
+
+  def unblock_all = payload["tasks"].each { |task| task["isCompleted"] = true }
+
+  def test_no_label_picks_the_top_takeable_ticket_and_never_a_spec
+    unblock_all
+    position(card_id("Spec:"), 1)
+    position(card_id("Adding members"), 2)
+
+    assert_equal <<~REPORT.chomp, next_card(nil)
+      card: #{line("Adding members")}
+      spec: #{line("Spec:")}
+      blockers:
+      - #{line("Documents inside")}: no Branch: comment
+      parent: AMBIGUOUS: no Branch: comment on #{board.card(card_id("Documents inside")).name}
+    REPORT
+  end
+
+  def test_no_label_skips_claimed_and_blocked_cards_above
+    unblock_all
+    claim(card_id("Contract edits"))
+    position(card_id("Contract edits"), 1)
+    payload["tasks"].each { |task| task["isCompleted"] = false if task["linkedCardId"] == card_id("Contract edits") }
+    position(card_id("Create a workspace"), 2)
+    position(card_id("Adding members"), 3)
+
+    assert_equal "card: #{line("Adding members")}", next_card(nil).lines(chomp: true).first
+  end
+
+  def test_no_label_on_a_ticket_without_a_feature_prints_no_spec
+    payload["cardLabels"].clear
+    assert_equal <<~REPORT.chomp, next_card(nil)
+      card: #{line("Contract edits")}
+      spec: none
+      blockers: none
+      parent: main
+    REPORT
+  end
+
+  def test_no_label_with_nothing_takeable_lists_the_ready_tickets
+    claim(card_id("Contract edits"))
+    report = next_card(nil).lines(chomp: true)
+
+    assert_equal "none:", report[0]
+    assert_includes report, "- #{line("Contract edits")}: claimed"
+    assert_equal 10, report.size
+  end
+
+  def test_an_effort_label_prints_the_frontier_in_position_order
+    map, *children = [ card_id("Spec:"), *ticket_ids.first(4) ]
+    add_label("effort:search", map, *children)
+    add_label("wayfinder:map", map)
+    move(map, "in-progress")
+    payload["tasks"].each { |task| task["isCompleted"] = true }
+    claim(card_id("Create a workspace"))
+
+    assert_equal <<~REPORT.chomp, next_card("effort:search")
+      card: #{line("Lookup cop")}
+      map: #{line("Spec:")}
+      frontier:
+      - #{line("Lookup cop")}
+      - #{line("Open a workspace")}
+      - #{line("Contract edits")}
+    REPORT
+  end
+
+  def test_an_empty_frontier
+    add_label("effort:search", card_id("Spec:"))
+    add_label("wayfinder:map", card_id("Spec:"))
+
+    assert_equal "card: none\nmap: #{line("Spec:")}\nfrontier: none", next_card("effort:search")
+  end
+end

data/test/lib/planka/planka_test_helper.rb

@@ -0,0 +1,63 @@
+require "json"
+require "minitest/autorun"
+require_relative "../../../lib/planka"
+
+# The fixture is the markdocs board as Plan 3 was published: a spec card and
+# nine ticket cards in ready-for-agent, each blocked on its predecessor(s).
+# Helpers edit a fresh copy of it into the state a test needs.
+module PlankaTestHelper
+  FIXTURE = File.expand_path("../../fixtures/files/planka/board.json", __dir__)
+
+  def before_setup
+    super
+    @planka_environment = %w[PLANKA_BASE_URL PLANKA_BOARD_ID].to_h { |key| [ key, ENV[key] ] }
+    ENV["PLANKA_BASE_URL"] = "http://planka.test:3000"
+    ENV["PLANKA_BOARD_ID"] = "test-board"
+  end
+
+  def after_teardown
+    @planka_environment.each { |key, value| value ? ENV[key] = value : ENV.delete(key) }
+    super
+  end
+
+  def payload
+    @payload ||= JSON.parse(File.read(FIXTURE)).fetch("included")
+  end
+
+  def board
+    Planka::Board.new(payload)
+  end
+
+  def card_id(name_prefix)
+    payload["cards"].find { |c| c["name"].start_with?(name_prefix) }.fetch("id")
+  end
+
+  def ticket_ids
+    labelled = payload["cardLabels"].map { |cl| cl["cardId"] }
+    with_criteria = payload["taskLists"].select { |tl| tl["name"] == "Acceptance criteria" }.map { |tl| tl["cardId"] }
+    payload["cards"].select { |c| labelled.include?(c["id"]) && with_criteria.include?(c["id"]) }
+      .sort_by { |c| c["createdAt"] }.map { |c| c["id"] }
+  end
+
+  # Moves the cards to done, completing the tasks linked to them as Planka does.
+  def close(*ids)
+    done = payload["lists"].find { |l| l["name"] == "done" }.fetch("id")
+    payload["cards"].each { |c| c["listId"] = done if ids.include?(c["id"]) }
+    payload["tasks"].each { |t| t["isCompleted"] = true if ids.include?(t["linkedCardId"]) }
+  end
+
+  def claim(id)
+    payload["cardMemberships"] << { "cardId" => id, "userId" => "1" }
+  end
+
+  def add_label(name, *ids)
+    label = payload["labels"].find { |l| l["name"] == name } ||
+      { "id" => "label-#{name}", "name" => name }.tap { |l| payload["labels"] << l }
+    ids.each { |id| payload["cardLabels"] << { "id" => "cl-#{name}-#{id}", "cardId" => id, "labelId" => label["id"] } }
+  end
+
+  def move(id, list_name)
+    list = payload["lists"].find { |l| l["name"] == list_name }.fetch("id")
+    payload["cards"].find { |c| c["id"] == id }["listId"] = list
+  end
+end

data/test/lib/planka/spec_sweep_test.rb

@@ -0,0 +1,35 @@
+require_relative "planka_test_helper"
+
+class Planka::SpecSweepTest < Minitest::Test
+  include PlankaTestHelper
+
+  def finished = Planka::SpecSweep.finished(board).map(&:id)
+
+  def test_a_spec_in_progress_whose_tickets_are_all_closed_is_finished
+    move(card_id("Spec:"), "in-progress")
+    close(*ticket_ids)
+
+    assert_equal [ card_id("Spec:") ], finished
+  end
+
+  def test_one_open_ticket_keeps_it_open
+    move(card_id("Spec:"), "in-progress")
+    close(*ticket_ids.drop(1))
+
+    assert_empty finished
+  end
+
+  def test_a_spec_with_no_tickets_is_left_alone
+    add_label("feature:empty", card_id("Spec:"))
+    payload["cardLabels"].reject! { |cl| cl["labelId"] != "label-feature:empty" && cl["cardId"] == card_id("Spec:") }
+    move(card_id("Spec:"), "in-progress")
+
+    assert_empty finished
+  end
+
+  def test_a_spec_that_isnt_in_progress_is_left_alone
+    close(*ticket_ids)
+
+    assert_empty finished
+  end
+end