@pi-unipi/kanboard 3.0.0-alpha.2 → 3.0.0-alpha.21

package/skills/kanboard/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: kanboard
-description: "Kanboard — the project's deferred-work board. Use when the user asks to note a task for later, to see what is on the board, or while working a board task: read it with `unipi-kanboard show`, add notes, block with a question, or file follow-up work."
+description: "Kanboard — the project's deferred-work board. Use when the user asks to note a task for later, to see what is on the board, or to work board tasks (e.g. do UNI-5): `start` a task before working on it and `finish` it with a summary when done; while working a board task: read it with `unipi-kanboard show`, add notes, block with a question, or file follow-up work."
 ---
 
 # Kanboard
@@ -16,27 +16,35 @@ Always pass the actor and the project, and call it by absolute path (it may not
 be on `PATH`):
 
 ```sh
-<binary> --actor agent --project <slug> list [--ready] [--json]
+<binary> --actor agent --project <slug> list [--ready] [--all] [--json]   # bare list = todo/in_progress/blocked/in_review/done only; --all adds backlog/cancelled/archived
 <binary> --actor agent --project <slug> show <ID>
-<binary> --actor agent --project <slug> next                     # what claim-next would pick + why
+<binary> --actor agent --project <slug> next                     # what would be picked next + why (read-only)
 <binary> --actor agent --project <slug> chain <ID>               # upstream deps + downstream dependents
 <binary> --actor agent --project <slug> search "<text>" [--all]  # id/title/body, archived excluded unless --all
 <binary> --actor agent --project <slug> add "<title>" [--status todo] [--after <ID>] [--body-file <f>] [--attach <file>]…
-<binary> --actor agent --project <slug> note <ID> "<text>"
+<binary> --actor agent --project <slug> note <ID> "<text>" [--attach <file>]…
 <binary> --actor agent --project <slug> attach <ID> <file> --note "<what it shows>"
 <binary> --actor agent --project <slug> attachments <ID>
 <binary> --actor agent --project <slug> edit <ID> --title|--body|--labels …   # only tasks you created, while in backlog/todo
-<binary> --actor agent --project <slug> move <ID> blocked --comment "<what you need>"
+<binary> --actor agent --project <slug> start <ID>                          # todo → in progress, claimed for your session (costs a -do slot)
+<binary> --actor agent --project <slug> finish <ID> --comment "<summary>" [--attach <file>]…   # in progress → in review, only a task you started (free)
+<binary> --actor agent --project <slug> move <ID> blocked --comment "<what you need>" [--attach <file>]…
 <binary> --actor agent --project <slug> link <ID> --after <DEP>
 <binary> --actor agent --project <slug> unlink <ID> --after <DEP>
 <binary> --actor agent --project <slug> order <ID> --top|--bottom|--before <ID>
-<binary> --actor agent --project <slug> queue <ID>… | queue --list            # your session's work queue (limit: setting queueMax, default 10)
-<binary> --actor agent --project <slug> unqueue [<ID>…]                      # no ids clears it
 ```
 
+There is **no queue and no runner** — the session works tasks itself
+(`/unipi:kanboard-autowork` just keeps offering the next ready task).
+`queue`, `unqueue`, `claim-next`, `set-run` and `edit --strategy/--plan` are
+removed and refused.
+
 `--json` gives machine-readable output for every subcommand (task objects carry
 `ready`, `waitingFor`, `depsStatus` and `staleness`).
 
+`list`/`search` show a one-line body excerpt; read a task's full description with
+`show <ID>` before editing or starting it.
+
 `settings show` reads the pi runtime and effective limits; `settings set`
 and `rotate-token` are user-only — the agent is refused.
 
@@ -45,10 +53,11 @@ and `rotate-token` are user-only — the agent is refused.
 | Move | Who |
 |---|---|
 | backlog ↔ todo | user, agent |
-| todo → in progress | **the runner only** (`claim-next`) |
+| todo → in progress | the agent with `start <ID>` (claims it for its session; costs a `-do` slot) |
 | edit a task | agent — only tasks it created, and only in backlog/todo |
-| in progress → in review | **the runner only** (when your turn ends) |
+| in progress → in review | the agent with `finish <ID> --comment` — only a task its own session `start`ed |
 | in progress → blocked | agent, system — **comment required** (what you need) |
+| in progress → todo | user or system `release` — comment required (the session died or gave the task up) |
 | blocked → todo | user only — comment required (the answer) |
 | in review → done | user only |
 | in review → todo/backlog | user only — comment required (rework note) |
@@ -65,26 +74,45 @@ lists them — read the files there directly if you need one.
 
 1. **Never pass `--actor user`.** That is an honour system: pretending to be the
    user to cancel a task or mark it done breaks the board's whole contract.
-2. **Never move a task to `in_review` or `done`.** The runner writes those when
-   your turn ends; claiming them yourself loses the summary and the review step.
+2. **Work the tasks yourself, in this session** (the user says "do UNI-5"):
+   **`start` a task before working on it, `finish` it with a summary when done**
+   — `start <ID>` before your first edit, `finish <ID> --comment "<what you
+   did>"` before your turn ends (or `move <ID> blocked --comment "<what you
+   need>"` if you cannot). `finish` and own-claim `blocked`/`note` are always
+   free; **`start` costs one of your `-do` task slots** — count the tasks a
+   request needs BEFORE starting anything, and if that is more than your
+   remaining slots, start none of them: say what you can do now and ask whether
+   to raise `kanboard.doTasks` or work in batches. In Review means "the agent
+   did the work, a human reviews" — never leave a task you started In Progress
+   (the board monitor will nudge you back to it). **Never move a task to
+   `done`.**
 3. **Never cancel.** If a task should be dropped, block it with
    `move <ID> blocked --comment "suggest cancel: <why>"` and let the user decide.
-4. **To ask the user something, block the task and stop**: `move <ID> blocked
-   --comment "<exactly what you need>"`. The answer arrives as a comment the next
-   time the task is claimed.
+4. **Follow the blocking rule in your task prompt**: by default work
+   autonomously and record assumptions with `note <ID> "assumed: <what/why>"`;
+   block (with a comment saying exactly what you need) only when you truly
+   cannot continue — `move <ID> blocked --comment "<what you need>"`.
 5. **Work only on the task you were given.** Follow-up work goes to the board as
    a new task in Backlog (`add "<title>"`), optionally `link <new> --after <ID>`.
-   A session holds one claim at a time, and at most `maxSessions` (default 2)
-   sessions may run tasks in a project — if the board refuses a claim, that is
-   why. You may
+   At most `maxSessions` (default 2) sessions may hold tasks in a project at
+   once — if the board refuses a `start`, that is why. You may
    block only the task your own session is running (`move <ID> blocked` checks
    `--session`/`UNIPI_KANBOARD_SESSION` against the claim).
-6. **To have tasks worked during a `/unipi:kanboard-do` turn, queue them** with
-   `queue <IDs>` (Todo tasks, up to the queue limit — setting `queueMax`, default 10) — the runner starts them one by one
-   after the turn ends. Never claim or start them yourself.
+6. **Sidekicks and subagents can read the board but never write it** — every
+   write is refused with "board writes are the lead's job". Brief them with the
+   task, then update the board yourself from their reports. (The lead session
+   works tasks itself; `/unipi:kanboard-autowork` just keeps offering the next
+   ready task in the same session — there is no separate worker.)
 7. Use `note <ID> "<text>"` for progress worth remembering (decisions, what you
    verified, what you left undone) — it is the activity log the next reader sees.
-8. Dependencies form a DAG: a task is ready only when every dep reached the chain
+8. **Write the `finish` / `blocked` comment as the report the user reads.** It
+   is shown as the task's status banner and opens in a reader, rendered as
+   markdown. Lead with one plain sentence (what you did, or what stops you),
+   then short paragraphs or `-` bullets separated by blank lines; put questions
+   for the user as a numbered list under `**Need from you:**`. Name files and
+   commands in backticks. Do not repeat a note you already wrote — the report
+   replaces it. Attach evidence with `--attach <file>`.
+9. Dependencies form a DAG: a task is ready only when every dep reached the chain
    gate (`in_review` by default, `done` when configured). Cancelled deps block
    forever, so unlink or re-plan instead of waiting. `chain <ID>` shows the
    whole line, `next` shows what would be picked and why others wait.
@@ -92,15 +120,21 @@ lists them — read the files there directly if you need one.
 ## Terminal-only execution
 
 The web UI can create, edit, reorder, link and move tasks, but it **never runs a
-task** — there is no run button. Work starts only from a terminal with
-`/unipi:kanboard-autowork start` (or the queue after a `/unipi:kanboard-do`). (The Done column's "Summarize & archive" does call the
-agent command set in the board's Settings, but only to write a summary.)
+task** — there is no run button. Work starts only from a terminal: the session
+itself, driven by `/unipi:kanboard-do` (a task-slot + write budget for one
+request) or `/unipi:kanboard-autowork` (the monitor keeps offering the next
+ready task in this session — no separate worker exists). (The Done column's
+"Summarize & archive" does call the agent command set in the board's Settings,
+but only to write a summary.)
 
 ## Attachments
 
 Users attach screenshots, logs and documents in the board UI; they appear in the
 text as markdown with `att:<ID>/<name>` references, and `show <ID> --json` lists
 them under `attachments` with an absolute `path` — read the file from there
-(use your image-reading tool for images). To hand back evidence, `attach` a file:
-it is stored beside the board and the comment embeds it, so the user sees the
-image or file inline.
+(use your image-reading tool for images). To hand back evidence (a screenshot,
+a log, a report), pass `--attach <file>` (repeatable) to `finish`, `move … blocked`
+or `note`, or use `attach <ID> <file> --note "…"`: the file is stored beside the
+board and the comment embeds it, so the user sees the image or file inline. A
+file's path written in the comment is replaced by the embed; otherwise the
+embed is appended. Attaching to a task you started is free.

package/src/badges.ts

@@ -0,0 +1,93 @@
+/**
+ * @pi-unipi/kanboard — transcript badges (user-only, never LLM context).
+ *
+ * A successful lead `start` / `finish` / `move <ID> blocked` appends a custom
+ * transcript entry rendered as `▣ UNI-30 started`, `✓ UNI-30 → In Review`,
+ * `⊘ UNI-30 blocked: <comment>`. Custom entries persist for the user but are
+ * outside the LLM context (same mechanism as core's progress bars).
+ */
+
+import type { ExtensionAPI, ThemeColor } from "@earendil-works/pi-coding-agent";
+import { Text, truncateToWidth, type Component } from "@earendil-works/pi-tui";
+
+import { kanboardInvocations } from "./guard.js";
+
+export const BADGE_ENTRY = "unipi:kanboard-badge";
+
+export type BadgeKind = "started" | "finished" | "blocked";
+
+export interface BadgeData {
+	kind: BadgeKind;
+	id: string;
+	/** Short human text (a blocked task carries what is needed). */
+	text?: string;
+}
+
+/** The badge kind a kanboard CLI call produces, or null. */
+export function badgeKindFor(sub: string, args: readonly string[]): BadgeKind | null {
+	if (sub === "start") return "started";
+	if (sub === "finish") return "finished";
+	if (sub === "move" && args.includes("blocked")) return "blocked";
+	return null;
+}
+
+/** Extract a badge from a successful kanboard bash call, or null. */
+export function badgeFromToolCall(toolName: string, input: Record<string, unknown> | undefined, isError: boolean): BadgeData | null {
+	if (isError || (toolName !== "bash" && toolName !== "powershell")) return null;
+	for (const invocation of kanboardInvocations(String(input?.command ?? ""))) {
+		const kind = badgeKindFor(invocation.sub, invocation.args);
+		if (!kind) continue;
+		const id = invocation.args.find((arg) => !arg.startsWith("-"));
+		if (!id) continue;
+		let text: string | undefined;
+		if (kind === "blocked") {
+			const flagIndex = invocation.args.indexOf("--comment");
+			text = flagIndex >= 0 ? (invocation.args[flagIndex + 1] ?? "").replace(/^["']|["']$/g, "") : undefined;
+		}
+		return { kind, id, ...(text !== undefined && text.length > 0 ? { text } : {}) };
+	}
+	return null;
+}
+
+export function badgeText(data: BadgeData): string {
+	if (data.kind === "started") return `▣ ${data.id} started`;
+	if (data.kind === "finished") return `✓ ${data.id} → In Review`;
+	const what = data.text ? `: ${data.text.slice(0, 80)}` : "";
+	return `⊘ ${data.id} blocked${what}`;
+}
+
+function badgeColor(kind: BadgeKind): ThemeColor {
+	if (kind === "started") return "accent";
+	if (kind === "finished") return "success";
+	return "warning";
+}
+
+/** Register the entry renderer (once per extension load; lead only). */
+export function registerBadgeRenderer(pi: ExtensionAPI): void {
+	try {
+		pi.registerEntryRenderer<BadgeData>(BADGE_ENTRY, (entry, _options, theme) => {
+			const data = entry.data;
+			if (!data || typeof data.id !== "string") return undefined;
+			const t = theme as unknown as {
+				fg?: (color: ThemeColor, text: string) => string;
+				bold?: (text: string) => string;
+			};
+			const line = t.fg?.(badgeColor(data.kind), badgeText(data)) ?? badgeText(data);
+			return new Text(t.bold ? t.bold(line) : line, 0, 0);
+		});
+	} catch {
+		// Renderer registration is UI-dependent; skip where unavailable.
+	}
+}
+
+/** Emit a badge for a successful tool result (lead tool_result hook body). */
+export function maybeBadgeToolResult(pi: ExtensionAPI, toolName: string, input: Record<string, unknown> | undefined, isError: boolean, width = 80): Component | null {
+	const badge = badgeFromToolCall(toolName, input, isError);
+	if (!badge) return null;
+	try {
+		pi.appendEntry<BadgeData>(BADGE_ENTRY, badge);
+		return new Text(truncateToWidth(badgeText(badge), width), 0, 0);
+	} catch {
+		return null;
+	}
+}

package/src/bin.ts

@@ -80,10 +80,12 @@ export function resolveBinary(env: NodeJS.ProcessEnv = process.env, from?: strin
   if (explicit) {
     return isRunnable(explicit) ? { path: explicit, source: "env" } : null;
   }
-  const packaged = platformPackagePath(from);
-  if (packaged && isRunnable(packaged)) return { path: packaged, source: "platform-package" };
+  // In a source checkout the dev build wins — the platform package can ship a
+  // stale prebuilt binary (seen on coffee: alpha.0 shadowed the debug build).
   const dev = devBuildPath();
   if (dev) return { path: dev, source: "dev-build" };
+  const packaged = platformPackagePath(from);
+  if (packaged && isRunnable(packaged)) return { path: packaged, source: "platform-package" };
   return null;
 }