Changes for version 0.601 - 2026-09-19
- A card left blocked in a terminal status (`done`/`archived`) no longer counts as an active blocker. `karr board`'s footer counts only live blocked cards, matching its claimed count, and breaks any hidden ones out as `N blocked (M in done)` so a done+blocked card cannot stay invisible. `karr context` applies the same rule to its blocked count and Blocked section -- a deliberate divergence from kanban-md, which counts them, so a shared context block can now hold a different blocked number (see docs/adr/0006). In both cases the flag and its `block_reason` are left untouched and stay reachable with `karr list --blocked --status done`.
- Prebuilt single-file Linux binaries (x86_64 and arm64) are now attached to each GitHub release, raw and as a `.tar.gz` with a `.sha256`, built with PAR::Packer so `karr` runs with no Perl or CPAN install. It bundles its own Perl; distribution convenience only, not faster than the CPAN install.
- `--local-only` on any writing command (`move`, `edit`, `handoff`, `create`, and every other command that syncs) writes to the board's local `refs/karr/*` and skips both the fetch and the push, so a mutation cannot block in the caller's timeout on an unreachable or silent configured remote. The refs are canonical local board state; `karr sync` publishes them once the remote is reachable again. Without the flag the fetch and push run exactly as before, and a board with no remote already syncs as a no-op either way.
- `karr list --status blocked` (and `--status not-blocked`) still exits 2
- neither is a status -- but the usage error now names the filter flag that was meant: `karr list --blocked` / `--not-blocked`. Any other invalid `--status` value keeps the plain `(valid: ...)` message.
- The bundled agent skill `kanban-issues-karr-cli` is a directory now: a short `SKILL.md` -- name yourself with `KARR_CLAIM`, read the board, work a card, create a card, create one on another repository's board, the output flags -- plus `references/*.md` an agent loads only when it needs them (cards, queries, claims, cross-board, config, storage, setup). The one-file skill had grown to 666 lines and went into the context whole on every trigger. `karr skill install`/`check`/`update` and `karr init --claude-skill` ship the whole directory, each file written in place as before; `check` reports an install that lacks a reference file as outdated and `update` adds it.
- Per-command `karr <cmd> --help` (and `karr <cmd> -h`) now renders karr's own compact one-line-per-option block: option names are hyphenated (`--claimed-by`, `--add-tag`, `--append-body`, `--depends-on`, `--claude-skill`, `--new-board`, `--accept-foreign-board`, `--write-to`, `--hide-no-board`), the built-in `--usage/-h/--help/--man` rows and the two blank lines around them are gone, and the shared `--dir` and `--quiet` options are suppressed so each page lists only what differs between commands. `karr-foundation --help` does the same for `--dry-run`. `-h` and `--help` are now the same page.
- `view` is now an alias for `show`: `karr view ID` (and every show form -- `view`, `view --me`, `view --json`, `view --compact`) behaves exactly like `karr show`.
- The claim name an agent works under is carried per process in the `KARR_CLAIM` environment variable: every command that takes `--claim` (`move`, `handoff`, `pick`, `edit`, and `create` when `--status` names a `require_claim` column -- a card filed into the backlog stays unclaimed for whoever picks it next) and `list --claimed-by` defaults to it when the flag is omitted, so an agent names itself once (`export KARR_CLAIM=$(karr agent-name)`) instead of threading the name through every call and no longer mismatches its own claim at handoff. An explicit `--claim` still wins, and `pick --claim` is no longer required. `karr agent-name` now returns the checkout's own directory name -- stable, meaningful, distinct per worktree -- rather than a random word, with `--unique` for several agents sharing one directory; a `require_claim` refusal names both `--claim` and `KARR_CLAIM`; and karr-foundation exports `KARR_CLAIM` per run. See ADR 0005.
- `create`, `init` and `agent-name` gained `--json`: create emits the created card in the `karr show --json` shape, and init and agent-name emit their result as JSON, so a script no longer parses human text.
- A claim-taking command that refuses a card held by someone else now names the way out -- release the claim or wait for `claim_timeout`
- not just the holder. `delete` gained `--claim NAME` so an agent can delete its own claimed card without stealing it; a card held by anybody else is still refused.
- `create --status` into a `require_claim` column no longer bypasses the claim rule: `create` gained `--claim NAME`, and creating a card straight into such a column without one is refused with the command line that would work.
- `list` and `pick` reject an unknown `--status` or `--priority` value with a usage error that names the configured values, instead of printing an empty list and exiting 0.
- `karr --version` prints the version and exits, before any board or repository lookup.
- `edit` can now change `--class` and `--estimate`, and gained `--clear-due` to drop a due date.
- `show` takes the `ID[,ID,...]` batch form the other task commands accept, printing the cards one after another (`--json` as an array); a missing id inside the batch is reported while the others still print, and the command exits 1.
- `list` shows the claim holder per card, and its footer reports how many done cards are hidden, so a `0 task(s)` line no longer hides a board whose every card is done.
- `karr completion bash|zsh|fish` prints a static shell completion script generated from the command and option tables; it never calls `karr` at completion time.
- `log` gained `--since` and `--action` to filter the activity log by time and by action.
- `list` and `board` gained `--group-by FIELD`, grouping the rendered rows under a heading per group; `--json` and `--compact` win over it, so it changes only the table.
- A `--no-color` flag sits beside the `NO_COLOR` variable, available both as `karr --no-color board` and `karr board --no-color`; colour is on only when stdout is a terminal, `NO_COLOR` is unset, and neither disabled it.
- Documentation brought back in line with the CLI. README and the bundled skill claimed `--json` on every board command; `create`, `init`, `agent-name`, `sync` and the payload commands (`backup`, `restore`, `destroy`, `set-refs`, `get-refs`) do not take it, and both texts now say which. The skill still described commands materializing a temporary file view while they run, which predates refs-first storage: commands read and write the refs directly, and `karr materialize` is the only thing that writes a file view. Its stored-card example gained the frontmatter fences and `lock_timeout`. README's "what is built" table said a chain could not be written from the CLI, two sections after showing `karr-foundation plan` doing exactly that; that table, the refs table and the option reference now name `plan` and `--input`. `perldoc karr` was cited for per-command options it never carried (`perldoc App::karr::Cmd::List` and its siblings are where they live); README spells the name generator `agent-name` as `karr --help` does, with `agentname` kept as the alias it is; `karr --help` lists the root `--done` option; and CONTEXT.md dropped a `--overview` option karr-foundation never had. `perldoc karr` gained the `dashboard` command it had never listed, and karr-foundation's exit-code notes named a `--deadline` option where the flag is `--wait`.
- Parent/subtask links (kanban-md's `--parent`) are a documented non-goal, not a gap: the `parent` field round-trips through `karr import` unchanged, but no karr command sets, filters, renders or sorts it. Relatedness between cards is `depends_on` (local ordering) and `needs` (cross-board). CONTEXT.md and README's stored-task-shape section now say so.
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 directory
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