App-karr
view release on metacpan or search on metacpan
lib/App/karr/Role/ClaimDefault.pm view on Meta::CPAN
=pod
=encoding UTF-8
=head1 NAME
App::karr::Role::ClaimDefault - Default a command's claim name from KARR_CLAIM when the flag is omitted
=head1 VERSION
version 0.602
=head1 DESCRIPTION
The one place the C<--claim> default is resolved. ADR 0005 carries the claim
name per process in the C<KARR_CLAIM> environment variable: every command that
takes C<--claim> (L<App::karr::Cmd::Move>, L<App::karr::Cmd::Handoff>,
L<App::karr::Cmd::Pick>, L<App::karr::Cmd::Edit>, L<App::karr::Cmd::Create>) and
C<karr list --claimed-by> (L<App::karr::Cmd::List>) defaults to C<$KARR_CLAIM>
when the flag is omitted. An explicit value on the command line always wins;
there is no silent fallback to anything else.
C<create>, C<move> and C<edit> read the default more narrowly, through
L</resolved_claim_for>: only when the card ends up in a column that requires a
claim (tickets #286, #303, #304). A card filed, promoted or annotated for
whoever picks it next stays unclaimed. C<pick> and C<handoff> always claim and
keep L</resolved_claim>.
The seven C<option claim> / C<option claimed_by> declarations differ in wording
and in whether they were C<required> (pick and handoff were), so they are left
where they are; what is shared is only the resolution -- L</resolved_claim> and
L</resolved_claimed_by> -- so no command reads C<$ENV{KARR_CLAIM}> or decodes it
itself.
C<KARR_CLAIM> crosses the character/octet boundary like every environment value
(CLAUDE.md, "characters inside, octets only at the edges"):
L<App::karr::Encoding/from_octets_from_env> decodes it here, the mirror of the
C<to_octets_for_env> path L<App::karr::Foundation::Runner> writes it through.
=head2 env_claim
my $name = $self->env_claim; # decoded KARR_CLAIM, or undef
The claim name from C<KARR_CLAIM>, decoded to a character string, or C<undef>
when the variable is unset or empty.
=head2 has_env_claim
... if $self->has_env_claim;
True when C<KARR_CLAIM> holds a non-empty value. A presence test, so it does
not decode -- the value never crosses the boundary here, only its emptiness is
asked.
=head2 resolved_claim
my $claim = $self->resolved_claim;
The effective claim for a command that declares C<option claim>: the explicit
C<--claim> value when one was given, otherwise L</env_claim>. This is who the
caller is -- what L<App::karr::Role::ClaimTimeout/check_claim> compares with
the card, and what C<pick> and C<handoff> stamp. A command that stamps a claim
only because the card lands somewhere asks L</resolved_claim_for>.
=head2 resolved_claim_for
my $claim = $self->resolved_claim_for( $status );
The claim to write on a card that ends up in C<$status>. An explicit
C<--claim> is returned for any status. L</env_claim> is returned only when
the board marks C<$status> C<require_claim>. Otherwise this returns C<undef>
and the card is not claimed.
The reason: a Claim is a lease held while working a card (CONTEXT.md). An
agent exports C<KARR_CLAIM> once per session. If every command stamped it, a
card that agent filed into the backlog, promoted to C<todo> or added a note to
would stay out of every other agent's C<karr pick> and C<karr list
--unclaimed> until C<claim_timeout> (tickets #286, #303, #304). A
C<require_claim> column is one the card is being worked in, so there the
C<KARR_CLAIM> name is the claim meant. It also satisfies the C<require_claim>
refusal exactly when it is written.
C<$status> is the card's status after the command: the C<create --status>,
the C<move> target, or the C<edit --status> (the card's current status when
that is omitted). An undefined C<$status> leaves only the explicit flag.
Whether the column takes the claim is not this method's question. C<backlog>
holds none (ticket k306): the environment never reaches it here, since it
needs no claim, and an explicit flag resolved for it is refused by the caller
(L<App::karr::Role::TaskMutation/check_held_back_claim>, and C<karr create>'s
own check).
=head2 resolved_claimed_by
my $owner = $self->resolved_claimed_by;
The C<list --claimed-by> counterpart of L</resolved_claim>, reading
C<option claimed_by>: the explicit filter value, otherwise L</env_claim>.
=head1 SUPPORT
=head2 Issues
Please report bugs and feature requests on GitHub at
L<https://github.com/Getty/karr/issues>.
=head2 IRC
Join C<#langertha> on C<irc.perl.org> or message Getty directly.
=head1 CONTRIBUTING
Contributions are welcome! Please fork the repository and submit a pull request.
=head1 AUTHOR
Torsten Raudssus <getty@cpan.org>
=head1 COPYRIGHT AND LICENSE
This software is Copyright (c) 2026 by Torsten Raudssus <torsten@raudssus.de> L<https://raudssus.de/>.
( run in 0.863 second using v1.01-cache-2.11-cpan-234fa220139 )