/ 
App-karr-0.602
/ App::karr::Role::ClaimDefault

NAME

App::karr::Role::ClaimDefault - Default a command's claim name from KARR_CLAIM when the flag is omitted

VERSION

version 0.602

DESCRIPTION

The one place the --claim default is resolved. ADR 0005 carries the claim name per process in the KARR_CLAIM environment variable: every command that takes --claim (App::karr::Cmd::Move, App::karr::Cmd::Handoff, App::karr::Cmd::Pick, App::karr::Cmd::Edit, App::karr::Cmd::Create) and karr list --claimed-by (App::karr::Cmd::List) defaults to $KARR_CLAIM when the flag is omitted. An explicit value on the command line always wins; there is no silent fallback to anything else.

create, move and edit read the default more narrowly, through "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. pick and handoff always claim and keep "resolved_claim".

The seven option claim / option claimed_by declarations differ in wording and in whether they were required (pick and handoff were), so they are left where they are; what is shared is only the resolution -- "resolved_claim" and "resolved_claimed_by" -- so no command reads $ENV{KARR_CLAIM} or decodes it itself.

KARR_CLAIM crosses the character/octet boundary like every environment value (CLAUDE.md, "characters inside, octets only at the edges"): "from_octets_from_env" in App::karr::Encoding decodes it here, the mirror of the to_octets_for_env path App::karr::Foundation::Runner writes it through.

env_claim

my $name = $self->env_claim;   # decoded KARR_CLAIM, or undef

The claim name from KARR_CLAIM, decoded to a character string, or undef when the variable is unset or empty.

has_env_claim

... if $self->has_env_claim;

True when 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.

resolved_claim

my $claim = $self->resolved_claim;

The effective claim for a command that declares option claim: the explicit --claim value when one was given, otherwise "env_claim". This is who the caller is -- what "check_claim" in App::karr::Role::ClaimTimeout compares with the card, and what pick and handoff stamp. A command that stamps a claim only because the card lands somewhere asks "resolved_claim_for".

resolved_claim_for

my $claim = $self->resolved_claim_for( $status );

The claim to write on a card that ends up in $status. An explicit --claim is returned for any status. "env_claim" is returned only when the board marks $status require_claim. Otherwise this returns undef and the card is not claimed.

The reason: a Claim is a lease held while working a card (CONTEXT.md). An agent exports KARR_CLAIM once per session. If every command stamped it, a card that agent filed into the backlog, promoted to todo or added a note to would stay out of every other agent's karr pick and karr list --unclaimed until claim_timeout (tickets #286, #303, #304). A require_claim column is one the card is being worked in, so there the KARR_CLAIM name is the claim meant. It also satisfies the require_claim refusal exactly when it is written.

$status is the card's status after the command: the create --status, the move target, or the edit --status (the card's current status when that is omitted). An undefined $status leaves only the explicit flag.

Whether the column takes the claim is not this method's question. 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 ("check_held_back_claim" in App::karr::Role::TaskMutation, and karr create's own check).

resolved_claimed_by

my $owner = $self->resolved_claimed_by;

The list --claimed-by counterpart of "resolved_claim", reading option claimed_by: the explicit filter value, otherwise "env_claim".

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)