@pi-unipi/kanboard 3.0.0-alpha.3 → 3.0.0-alpha.31

package/README.md

@@ -1,218 +1,130 @@
-# @pi-unipi/kanboard
+# Kanboard
 
-The pi half of **kanboard v3**: a per-project board for deferred work. The
-storage, transition rules and web UI live in the Rust binary
-([`crates/kanboard`](../../crates/kanboard) — one writer for every change); this
-package is the terminal-side bridge: commands, the task runner, hub settings and
-the `kanboard` skill.
+Keep a per-project board of work for later, and let the agent work the tasks when you allow it.
 
-Spec: [`docs/specs/2026-09-24-kanboard-v3-design.md`](../../docs/specs/2026-09-24-kanboard-v3-design.md).
+`@pi-unipi/kanboard` · part of [UniPi](../../README.md)
 
-## Commands
+![Kanboard dashboard: tasks that need you, the next ready task and project health](../../docs/assets/screenshots/kanboard-dashboard.png)
 
-`/unipi:kanboard [open|close|onboard|status|doctor]` — bare lists everything
-(display-only, never enters the LLM context):
+![Kanboard board: lanes from Backlog to Done with task cards](../../docs/assets/screenshots/kanboard-board.png)
 
-| Sub | What it does |
-|---|---|
-| `open [--host H] [--port N]` | Ensure the daemon (reuse a healthy one, else spawn `serve` detached) and print `http://127.0.0.1:<port>/p/<slug>`. The browser opens only when `openBrowser` is on. |
-| `onboard` | `project add` for this workspace and remembers the slug. Idempotent. |
-| `close` | Shut down the board daemon — the web UI goes offline until the next `open`. Running tasks are unaffected. |
-| `status` | Daemon pid/port, project counts, active claims (session/pid/host/staleness), this session's queue, and the runner's current task. |
-| `doctor` | ✓/✗ setup check (binary, daemon health, project, summary agent, bind, claims) as a display-only message. |
+## What it does
 
-The other three commands are separate slash commands:
+- Keeps tasks in lanes: Backlog, Todo, In Progress, In Review, Blocked, Done, Cancelled and Archived.
+- Opens a web board for each project. The board updates when the agent or the CLI changes a task.
+- Lets you add a task from the prompt with no agent turn.
+- Lets the agent work tasks only within a budget that you give it, or in autowork.
+- Asks the agent to continue a task that it started and did not finish.
+- Stores tasks as markdown files. The Rust binary `unipi-kanboard` writes all changes. Refer to [the crate README](../../crates/kanboard/README.md).
 
-| Command | What it does |
-|---|---|
-| `/unipi:kanboard-add [-p 1-5] [--after ID] [--status backlog\|todo] <title>` | Capture a task — no agent turn. Lines below the title are the body; existing file paths pasted there are attached. `-p` maps 1 none · 2 low · 3 medium · 4 high · 5 urgent. |
-| `/unipi:kanboard-do <request>` | Reveal the skill and hand the request to the agent with board writes enabled for that turn. The agent may add/move/queue/note; it cannot run tasks — queued ids are drained by the runner when the turn ends. |
-| `/unipi:kanboard-autowork start\|stop` | `start` runs ready tasks one by one (queue order first, then `claim-next`); `stop` finishes the current task, then stops. |
-
-The old `add`/`work`/`stop` subcommands and bare-text capture now just point at
-these commands.
-
-## Runner (`/unipi:kanboard-autowork start`)
-
-One job per session. The **runner owns the lifecycle transitions** the agent is
-not allowed to write:
-
-1. `claim-next --session <sid> --pid <ppid> --host <host> --gate <chainGate>` —
-   nothing ready → `Nothing ready (N waiting on deps, M blocked)`.
-2. **The task's labels decide how it runs** (`edit <ID> --strategy
-   none|goal|ralph|swarm|graph` and `--plan yes|no`; `auto`/unset = jev picks).
-   jev gets one `choice` call with only the unset questions (title + body
-   ≤2000 chars): strategy criteria none/goal/ralph/swarm/graph + plan yes/no.
-   jev null → `none` + no plan; the decision is logged to
-   `~/.unipi/logs/kanboard.log` with `UNIPI_DEBUG_KANBOARD=1`.
-3. `set-run --mode`, then the task goes to the agent as a user message: title,
-   body, last 10 activity entries, each dependency with its status and last note,
-   and the rules (block with a comment to ask a question; never write
-   `in_review`/`done`/`cancelled`; work only on this task).
-   - **plan=yes** → plan mode is entered through workflow's `unipi:plan-enter`
-     runner first; approval stays interactive; a discarded plan releases the
-     task to Todo with `plan discarded`. The chosen strategy applies to the
-     work turn after approval (deferred until `planModeChanged`).
-   - **goal** → long-horizon's `unipi:goal-start` runner starts a goal with the
-     task as the objective; the goal id is recorded with `set-run --goal` and
-     completion is read back with `unipi:goal-status`.
-   - **swarm / graph** → long-horizon's `unipi:lh-explicit` runner sets the
-     explicit mode for the work turn.
-   - **ralph** → `unipi:ralph-start` starts the checklist loop (task title +
-     body as the checklist file); with no `- [ ]` items or a failed start it
-     falls back to goal, then none.
-4. Run end (a `/plan` settle after the last `agent_end`, once the agent reports
-   idle with no queued messages): the task is re-read — if the agent blocked it,
-   that is respected and reported (`▣ UNI-12 blocked: <comment>`) and the loop
-   continues; otherwise `release --to in_review --comment <last assistant text
-   ≤500 chars>`. `Esc` (aborted turn) → `release --to todo --comment "interrupted
-   by user"` and the loop stops. Session shutdown → `release --to todo` with
-   `session ended`.
-5. After each task: `✓ UNI-12 → In Review: <first line>`, then the loop takes
-   the next id from the session **queue** (`claim-next --id`; entries that went
-   stale are dropped with a notice), falls back to `claim-next` while autowork
-   is on, and stops when nothing is ready. The event loop is never blocked.
-
-Footer: `▣ UNI-12 · <strategy>[ +plan]` while a task runs. The claimed task is persisted with
-`pi.appendEntry("unipi:kanboard-runner", …)`, so `/reload` or a resume offers to
-resume it or releases it to Todo.
-
-## Settings (hub section "Kanboard")
-
-| Setting | Default | Notes |
-|---|---|---|
-| `chainGate` | `in_review` | `done` waits for a finished dependency |
-| `idleMin` | `10` | Passed to `serve --idle-min` |
-| `port` | `0` | Passed to `serve --port` (0 = OS-assigned) |
-| `archiveAfterDays` | `0` | > 0 → `archive-sweep --after-days N` on session start (fire and forget) |
-| `openBrowser` | `false` | Open the board in a browser on `open` |
-| `requireAuth` | `false` | Also require the access token on 127.0.0.1 (remote always does) |
-| `keepToken` | `false` | Reuse `<home>/token` across daemon restarts |
-| `queueMax` | `10` | Tasks a session may queue (0 = unlimited); passed to the CLI as `UNIPI_KANBOARD_QUEUE_MAX` |
-| `maxSessions` | `2` | Distinct sessions running tasks per project (`UNIPI_KANBOARD_MAX_SESSIONS`) |
-| `turnAddLimit` | `20` | `add` calls allowed per -do turn or runner task (0 = unlimited) |
-| *actions* | | `Open board…`, `Stop daemon`, `Summary agent command…`, `Rotate access token` |
-
-`Summary agent command…` writes through `settings set agent-command` and
-`Rotate access token` runs `rotate-token` — both are **user-only** (actor=agent
-is refused), as are `settings set` calls generally. `settings show` is read-only.
-
-## Binary resolution
-
-1. `UNIPI_KANBOARD_BIN` (explicit path)
-2. `@pi-unipi/kanboard-<platform>-<arch>/bin/unipi-kanboard[.exe]` (K4 ships these)
-3. the dev build `<repo>/crates/kanboard/target/{release,debug}/unipi-kanboard`
-
-Nothing found → every command reports
-`kanboard binary unavailable for <platform>-<arch>` and does nothing else.
-
-**Agent bash env:** pi has no extension-level mechanism to add env vars to the
-`bash` tool (only replacing bash via `registerTool` + `BashToolOptions`, which
-would change tool schemas mid-session and break the prefix cache — spec principle
-4 forbids that). So the task prompt and the skill pass `--actor agent --project
-<slug>` explicitly and call the binary by absolute path.
-
-## Skill
-
-`skills/kanboard/SKILL.md` describes the CLI, the lanes, who may move what, and
-the rules agents must follow. It is a normal pi skill (jev skill-judging can
-reveal it on intent), and `/unipi:kanboard-do` force-reveals it by emitting
-`unipi:skills:reveal`, which utility turns into the usual append-only reveal
-message — the system prompt is never touched.
-
-## Platforms and packaging
-
-| Platform | npm package | Rust target | Notes |
-|---|---|---|---|
-| Linux x64 | `@pi-unipi/kanboard-linux-x64` | `x86_64-unknown-linux-musl` | static-pie, 3.9 MB |
-| Linux arm64 | `@pi-unipi/kanboard-linux-arm64` | `aarch64-unknown-linux-musl` | static |
-| macOS arm64 | `@pi-unipi/kanboard-darwin-arm64` | `aarch64-apple-darwin` | |
-| macOS x64 | `@pi-unipi/kanboard-darwin-x64` | `x86_64-apple-darwin` | cross-built from macos-14 |
-| Windows x64 | `@pi-unipi/kanboard-win32-x64` | `x86_64-pc-windows-msvc` | |
-
-They are **optional dependencies** of this package (`os`/`cpu` gated), so `npm install`
-pulls exactly one. `.github/workflows/kanboard-binaries.yml` builds them (tests +
-clippy on native targets, release build per target, artifact per platform) and, on
-a `v*` tag, attaches the binaries to the GitHub release. Publishing to npm:
+## Quick start
+
+UniPi installs this package:
 
 ```bash
-npm run publish:kanboard -- --dry-run   # what would ship
-npm run publish:kanboard                # publishes, or skips loudly
+pi install npm:@pi-unipi/unipi
 ```
 
-The script **skips any platform package whose `bin/` is empty** (and exits 2), so
-an empty platform package can never be published. CI publishes only when an
-`NPM_TOKEN` secret exists — this repository has none, so the release job attaches
-artifacts and says so.
-
-Local packaging proof (no registry, no network):
+To install this package alone:
 
 ```bash
-node scripts/test-kanboard-packaging.mjs
-# packs packages/kanboard + the linux-x64 platform package, installs both into a
-# temp node_modules, resolves the binary through src/bin.ts and runs --version
+pi install npm:@pi-unipi/kanboard
 ```
 
-## Remote access
+npm installs the binary for your platform as an optional package: Linux x64 and arm64, macOS x64 and arm64, and Windows x64.
 
-The daemon binds `127.0.0.1` by default — local only, no token. For access from
-another machine either **tunnel** it (nothing to configure):
+1. Run `/unipi:kanboard onboard` to register the project.
+2. Run `/unipi:kanboard-add Fix the flaky login test` to add a task.
+3. Run `/unipi:kanboard open` and open the link that it prints.
+4. Run `/unipi:kanboard-do work the login tasks` to let the agent work them.
 
-```bash
-ssh -N -L 37473:127.0.0.1:37473 <hostname>   # then open http://127.0.0.1:37473
-```
+## Commands
 
-…or bind a reachable interface, which turns on the **token gate**:
+| Command | What it does |
+|---|---|
+| `/unipi:kanboard` | Lists the commands. |
+| `/unipi:kanboard open [--host H] [--port N]` | Starts the board daemon if it does not run, and prints the board link. |
+| `/unipi:kanboard close` | Stops the board daemon. Tasks in progress do not change. |
+| `/unipi:kanboard onboard` | Registers this project. You can run it again with no effect. |
+| `/unipi:kanboard status` | Shows the daemon and the active claims. |
+| `/unipi:kanboard show [--all]` | Shows the board in the chat. |
+| `/unipi:kanboard doctor` | Examines the setup: binary, daemon, project and bind address. |
+| `/unipi:kanboard-add [-p 1-5] [--after ID] [--status backlog\|todo] <title>` | Adds a task. Lines below the title become the description. A file path in the description becomes an attachment. |
+| `/unipi:kanboard-do <request>` | Gives the request to the agent with a task budget. `off` removes the budget. |
+| `/unipi:kanboard-autowork start\|stop` | `start` lets the agent work all ready tasks, one at a time. `stop` stops the offers of new tasks. |
 
-```bash
-/unipi:kanboard open --host 0.0.0.0 --port 37473     # every interface
-/unipi:kanboard open --host tailscale                # the tailnet IPv4
-```
+Priority `-p`: 1 none, 2 low, 3 medium, 4 high, 5 urgent.
 
-`--host` and `--port` override the `host`/`port` settings for that invocation
-only. `tailscale` resolves through `tailscale ip -4` (clear error when tailscale
-is not installed). For a wildcard bind the printed URLs cover the machine
-hostname, every non-internal IPv4 and the tailnet address, and a warning says
-`board is reachable from the network; anyone with the link can edit it`.
+The output of these commands shows in the chat. It does not go into the model context.
 
-**Token model.** Any non-loopback bind generates a 32-byte token (base64url) and
-writes it to `daemon.json` alongside `host`. Every request must carry it:
+## Task budget
 
-- `?t=<token>` — sets an `HttpOnly; SameSite=Strict` cookie and 303-redirects to
-  the same URL without the parameter (so the token leaves the address bar),
-- the `kb_token` cookie, or
-- `Authorization: Bearer <token>`.
+`/unipi:kanboard-do` gives the agent two budgets:
 
-Missing or wrong tokens answer `401` with a page saying to open the link printed
-by `/unipi:kanboard open`. `/api/health` stays reachable but returns only
-`{ok, version}` (no pid) off-loopback, and POSTs are refused when their `Origin`
-does not match the request `Host` (drive-by CSRF), in both modes. Loopback binds
-keep no token at all.
+- **Task slots** (`doTasks`, default 5). Each `start` uses one slot.
+- **Board writes** (`doWrites`, default 10). `add`, `edit`, `link`, `order`, a move between Backlog and Todo, and a `note` on a task of another session each use one write.
 
-Changing the binding needs a restart: if a daemon already runs with a different
-host/port, `serve` reports `bindingChanged` and `/unipi:kanboard open` stops the
-old one and starts the new one (`restarted kanboard on 0.0.0.0:37473`). The
-daemon runs no jobs, so nothing is lost.
+Some operations are always free: reads, and `finish`, `move <ID> blocked`, `note` and `attach` on tasks that this session started. The budget stays until the agent uses it. A new `-do` fills the budget again. It does not add to the old budget.
 
-## Storage
+In autowork, the agent has no budget. It can use any mode, for example goal or ralph.
 
-`~/.unipi/kanboard/` (`UNIPI_KANBOARD_HOME` overrides it): `daemon.json` +
-`daemon.lock` for the daemon, and `projects/<slug>/{project.json,board.lock,tasks/*.md,queues/<session>.json}`.
-The extension never edits those files — the binary owns them.
+Subagents and sidekicks can read the board, but cannot write to it. The guard tells them to report to the lead.
 
-## Troubleshooting
+## Settings
 
-| Symptom | Fix |
-|---|---|
-| `kanboard binary unavailable for <platform>-<arch>` | No `UNIPI_KANBOARD_BIN`, no platform package and no dev build. Build `crates/kanboard` (`cargo build --release`) or set `UNIPI_KANBOARD_BIN`. |
-| The board says *"N task file(s) need repair"* | A file was edited by hand. One bad file no longer blocks the board (it is skipped and reported); run `unipi-kanboard validate --fix`, then `validate`. |
-| `UNI-5 is unreadable: … (line N)` | That task's own file is broken — repair it before moving/noting it. |
-| The daemon looks stale | `unipi-kanboard status` (pid + liveness), then `/unipi:kanboard close`, `unipi-kanboard stop` (SIGTERM, ≤3s) or the hub's **Stop daemon** action. |
-| Nothing is ready | `unipi-kanboard list --ready --json` shows `waitingFor`; a cancelled dependency blocks forever — `link`/`unlink` to re-plan. |
-| The runner prompts for permission on every board call | Fixed in auto mode: `unipi-kanboard … --actor agent` is allow-listed by the permission gate (ask mode still asks). |
+Open `/unipi:settings` → **Kanboard**. The file is `~/.unipi/config/kanboard/config.json`.
 
-## Tests
+| Key | Default | What it does |
+|---|---|---|
+| `chainGate` | `in_review` | Status that a dependency must reach before the next task is ready: `in_review` or `done`. The web board uses it. |
+| `idleMin` | `10` | Minutes with no board open before the daemon stops. |
+| `host` | `127.0.0.1` | Bind address. Any other address needs an access token. |
+| `port` | `0` | Daemon port. `0` lets the OS select a port. |
+| `archiveAfterDays` | `0` | Archives done and cancelled tasks after this many days. `0` turns it off. |
+| `retentionDays` | `90` | Moves archived and cancelled tasks to cold storage after this many days. |
+| `openBrowser` | `false` | Opens the board in a browser on `open`. |
+| `requireAuth` | `false` | Asks for the token on `127.0.0.1` too. |
+| `keepToken` | `false` | Uses the same token after a daemon restart. |
+| `maxSessions` | `2` | Number of sessions that can hold In Progress tasks in one project. |
+| `turnAddLimit` | `20` | `add` calls in one turn. `0` means no limit. |
+| `reminders` | `true` | Reminds the agent to `start` a Todo task before it edits files. |
+| `doTasks` | `5` | Task slots that one `-do` gives. |
+| `doWrites` | `10` | Board writes that one `-do` gives. |
+
+At session start, Kanboard runs `archive-sweep` when `archiveAfterDays` or `retentionDays` is more than 0.
+
+## How it works
+
+Kanboard has no task runner. The agent works each task in your session. When a run ends, a monitor on the [turn arbiter](../../docs/architecture/turn-arbiter.md) can add one message to continue:
+
+- **Claims** (priority 50). A task that this session started is still In Progress. The monitor asks the agent to continue, finish or block it.
+- **Next task** (priority 40). Autowork is on and a ready task exists. The monitor offers it. When no task is ready, autowork stops.
+
+The monitor waits for a [long-horizon](../../docs/architecture/long-horizon.md) owner (priority 100) and for pending events. It stops after you press `Esc` or a run fails. It also stops after 2 runs with no tool calls, after 5 messages for one task, or after 3 offers of one task in autowork.
+
+At session start, Kanboard releases claims of dead processes. At session end, it moves the open claims of this session back to Todo. The next start shows a notice about these tasks.
+
+## Remote access
+
+The daemon listens on `127.0.0.1` by default and needs no token. To use the board from another machine, use an SSH tunnel:
 
 ```bash
-npm test -w packages/kanboard     # bin resolution, commands, runner, settings
+ssh -N -L 37473:127.0.0.1:37473 <hostname>
 ```
+
+You can also bind another address, for example `/unipi:kanboard open --host 0.0.0.0 --port 37473` or `--host tailscale`. Then the daemon makes an access token, and the printed link contains it. Anyone with the link can edit the board.
+
+## Troubleshooting
+
+| Problem | Fix |
+|---|---|
+| `kanboard binary unavailable for <platform>-<arch>` | Set `UNIPI_KANBOARD_BIN` to the binary path, or build `crates/kanboard` with `cargo build --release`. |
+| The board says that some task files have errors | Run `unipi-kanboard validate --fix`, then `unipi-kanboard validate`. |
+| The daemon does not respond | Run `/unipi:kanboard close`, then `/unipi:kanboard open`. |
+| No task is ready | Run `unipi-kanboard list --ready --json` and read `waitingFor`. A cancelled dependency blocks a task. |
+
+## See also
+
+- [Kanboard crate: CLI, daemon and JSON API](../../crates/kanboard/README.md)
+- [Turn arbiter](../../docs/architecture/turn-arbiter.md)
+- [Commands reference](../../docs/reference/commands.md)