Changes for version 0.602 - 2026-09-30
- `backlog` is now held back. `karr pick` and `karr-foundation` never take a card from it, whatever the filters, and a board with only backlog cards left counts as drained (skipped while unchanged, `on_drained` runs, `board_actionable=no`). `karr pick --status` naming `backlog`, and `pick --move backlog`, are refused as usage errors (exit 2) pointing at `karr move ID todo`. A card in backlog holds no claim: an explicit `--claim` onto it is refused by `create` (the default status included), `edit` and `move` (exit 1), and a move into backlog -- `move` or `edit --status` -- releases the claim the card carried. `todo` is the pool that is picked from; `move ID in-progress --claim NAME` still takes a backlog card up directly. The bundled skills and foundation's agent prompts say that promoting out of backlog is the maintainer's call. A board without a `backlog` column is unaffected.
- With `KARR_CLAIM` exported, `karr edit` and `karr move` no longer claim every card they touch; the env name is written only when the card ends up in a `require_claim` status (the rule `create` already follows). A note, a tag or a backlog -> todo promotion leaves the card free to pick. `edit --release` no longer claims the card back. An explicit `--claim` still stamps on any status but `backlog` (see above).
- `karr-foundation` treats a card as finished when it is in the board's own final status (or archived), not only `done`/`archived`. A board whose last column has another name (e.g. `shipped`) is now seen as drained: an unchanged board is skipped instead of starting an agent every tick, the drain reports its progress, `on_drained` runs, and chain prechecks read `board_actionable=no`.
- The bundled agent skill `kanban-issues-karr-cli` is split in two: `kanban-issues-karr-coordination` (reading a board, picking, creating and routing cards, config, sync) and `kanban-issues-karr-ticket` (working the one card an agent was handed). `karr skill install`, `check` and `update` and `karr init --claude-skill` handle both as one set; every result line and `--json` entry now names its skill. A leftover `kanban-issues-karr-cli/` directory is removed by `install`, `update` and `init --claude-skill` (reported as `removed`), and `check` reports it as `stale` and exits 1, so `karr skill update` alone migrates an old install. `karr skill show` prints both `SKILL.md` files, or only the one named (`karr skill show kanban-issues-karr-ticket`); its `--json` output is now an array of `{skill, content}` objects instead of one `{content}`.
- Local task ids accept the house `kNNN` spelling: `karr show k30` names the same card as `karr show 30`, and a leading `k`/`K` works anywhere a bare number does -- move, edit, delete, archive, unlock, handoff, needs, show, mixed batches (`k30,31,K32`), `log --task`, the `--depends-on`/`--add-depends-on`/`--remove-depends-on` flags and the id side of a cross-board `BOARD#ID` reference. Any other token is left untouched and still fails as before; `log --task` answers a value that is not an id -- a negative number, or `0` in any spelling (`0`, `k0`, `00`), since task ids start at 1 -- with a usage error (exit 2) naming the value.
- Release-asset names are tidied. The arm64 binary and tarball are now named `...-linux-aarch64` (was `-linux-arm64`) to match the `x86_64` naming, and the per-file `.sha256` sidecars are replaced by a single `karr-<version>-checksums.txt` (verify with `sha256sum -c --ignore-missing karr-<version>-checksums.txt`, which checks only the assets you downloaded -- a plain `-c` fails on the ones you did not) covering every asset. The raw binary and the `.tar.gz` are both still shipped per arch.
- The prebuilt Linux binaries now carry the bundled skills: `karr skill install|show|check|update` and `karr init --claude-skill` failed in them with "Could not find .../SKILL.md. Is App::karr properly installed?", because the build never packed share/. The release build now fails a binary that cannot install every bundled skill.
- `karr-foundation --dry-run` in ticket mode no longer logs a STALL for the agent run it did not start.
- `karr init --claude-skill` looks up the bundled skills before it writes anything, so an installation that cannot find them fails without leaving a board, `.gitignore` entries or an empty `.claude/skills/` directory behind, and the same command works once the installation is fixed.
Documentation
Kanban Assignment & Responsibility Registry
Single-shot foundation daemon for periodic karr agent execution
Modules
Kanban Assignment & Responsibility Registry
Activity log writer for karr board operations
Derive a claim-safe agent name from a checkout directory
Shared board-level computations for the rendering commands
Ref-backed board storage for karr
Print a claim name derived from the checkout directory
Archive a task (soft-delete)
Export the ref-backed karr board as YAML
Show board summary
Generate shell completion scripts for bash, zsh, and fish
View or modify board configuration
Generate board context summary for embedding
Create a new task
Multi-board overview of every karr board under a directory tree
Delete a task
Destroy the ref-backed karr board
Disable automated agent runs on this board
Modify an existing task
Re-enable automated agent runs on this board
Fetch helper payloads from a Git ref
Hand off a task for review
Import a tasks/ file view back into the ref-backed board
Initialize a new karr board
List tasks with filtering and sorting
Show activity log
Write the ref-backed board out as a tasks/ file view
Show flow metrics: throughput, lead/cycle time, flow efficiency, aging work
Change a task's status
Report and resolve cross-board dependencies
Atomically find and claim the next available task
Migrate an old board off double-encoded UTF-8 and off impossible start stamps
Restore the ref-backed karr board from YAML
Store helper payloads in a Git ref
Show full details of a task
Install, check, and update bundled agent skills
Sync karr board with remote
Show and break task pick locks
Board configuration management
Cross-board dependencies -- a link from a card here to a card on another board
The one dispatch path shared by bin/karr and the in-process test runner
The character/octet boundary for karr
Turn internal errors into one clean user-facing line
Single-shot foundation daemon -- periodic agent execution across karr boards
karr-foundation agent definitions, invocation contract and availability
karr-foundation chain and run-log storage under refs/karr-foundation/*
karr-foundation's judgement layer -- the coordination agent, called only on deviation
karr-foundation chain executor -- picks a ready step, runs it, writes its state back
karr-foundation concurrency limits -- machine ceiling, per-agent estimates, chain header
karr-foundation read-only overview -- multi-board status dashboard
karr-foundation ticket selection -- the one card a ticket-mode run is about
karr-foundation question mailbox under refs/karr-foundation/questions/*
karr-foundation command execution -- fork/pipe/select tee + run classification
karr-foundation per-repo state -- lock file, JSON state, cooldown backoff
Git operations for karr sync (native via Git::Native + libgit2, with a git-CLI transport fallback)
Lock management via Git refs
Role providing board discovery, sync lifecycle, and task access
Role providing minimal board discovery and config access
Default a command's claim name from KARR_CLAIM when the flag is omitted
Shared claim timeout logic
Role providing option-aware CLI positional-argument parsing
Shared colour decision for the renderers that colour their output
Role providing the --compact output option
Turn the dependency ids a command was given into validated numbers
Warn when a card is taken up while its dependencies are unfinished
Normalize MooX::Options option-parse errors to exit code 2 (ADR 0002)
Role providing common output format options
The one definition of which card karr pick may hand out, and in what order
The one way karr finds and writes the bundled skill directories
Role providing sync lifecycle with retry and guard insurance
The one guarded path for changing an existing task
Push guard with automatic retry on scope exit
Task object representing a single kanban card