NAME
App::karr::Foundation::Picker - karr-foundation ticket selection -- the one card a ticket-mode run is about
VERSION
version 0.600
DESCRIPTION
App::karr::Foundation::Picker answers one question for App::karr::Foundation's mode: ticket: which card is this agent run about? It applies karr pick's eligibility rules and karr pick's ranking to one board and returns a task id -- and stops there. It claims nothing, locks nothing and writes nothing.
Applies, not mirrors: the rules are App::karr::Role::PickRules, composed here and composed by App::karr::Cmd::Pick, so both ask one definition. They were written out twice until ticket #198, and only their having been copied from one another kept them agreeing -- while foundation naming a card the agent's own karr pick would not have handed it is a coordinator arguing with its own board.
Not claiming and not locking is the whole difference to App::karr::Cmd::Pick, and it is deliberate. Foundation already holds the board's .karr.lock for the length of the run and the fleet rule is one agent per repository, so nothing else can take the card while the run lasts; a second owner would only add a claim with a lifetime nobody watches. The claim belongs to the agent, which mints its own name with karr agentname and has to keep using that same name for move and handoff (#176) -- a name foundation invented could not be handed over without inventing a protocol for it. So an agent that dies mid-run leaves at most its own claim, cleared by the board's claim_timeout or by karr unlock, exactly as it does today.
Claim expiry rides along with those rules, from App::karr::Role::ClaimTimeout, which App::karr::Role::PickRules composes: reading an expired claim correctly means parsing an RFC3339 stamp that may carry a fraction and an offset (#57), and that parser exists once. Foundation has to see expiry, or a crashed agent's claim would take its card out of the assignable set for good and a board whose only open card carries such a claim would go quiet for ever -- nothing would run, so nothing would reap the claim.
store
The App::karr::BoardStore for the board "next_ticket" picks from. Required.
json
Always false. Exists only to satisfy App::karr::Role::ClaimTimeout's contract; karr-foundation's ticket-mode selection has no --json and never emits any.
quiet
Always true, for the same reason as "json": nothing here prints, ever -- karr-foundation says what it did through .karr.log instead.
next_ticket
my $id = App::karr::Foundation::Picker->new( store => $store )->next_ticket;The id of the card a mode: ticket run should be about, or undef when the board has none to give. Eligibility is "pickable" in App::karr::Role::PickRules with --status and --tags absent -- the same call karr pick makes, not a mirror of it: not in a terminal status (the board's own final column and archived, not a hardcoded done), not blocked, and not held by a live claim, where a claim past the board's claim_timeout no longer blocks anybody here either. Ranking is "pick_rank" in App::karr::Role::PickRules: class of service, then priority, then id -- with kanban-md's one exception, where two fixed-date cards are ranked by the sooner due date before priority is asked (#233).
Unmet dependencies are not filtered out, which is karr pick's behaviour and comes from applying its rules: nothing about depends_on blocks anything in karr, the command hands the card over and warns (#123). Filtering here would make foundation stricter than the board it coordinates.
Nothing is written and nothing is locked, so the answer is a hint that ages: by the time the agent reads it the card may have moved. That is the same staleness every karr client lives with, and foundation's per-repo lock plus the one-agent-per-repository rule is what keeps it from mattering within a run.
SUPPORT
Issues
Please report bugs and feature requests on GitHub at https://github.com/Getty/karr/issues.
IRC
Join #langertha on irc.perl.org or message Getty directly.
CONTRIBUTING
Contributions are welcome! Please fork the repository and submit a pull request.
AUTHOR
Torsten Raudssus <getty@cpan.org>
COPYRIGHT AND LICENSE
This software is Copyright (c) 2026 by Torsten Raudssus <torsten@raudssus.de> https://raudssus.de/.
This is free software, licensed under:
The Artistic License 2.0 (GPL Compatible)