@netnodeag/kraftwerk 0.80.0 → 0.82.0

package/README.md

@@ -259,6 +259,7 @@ kraftwerk workspaces                    # every workspace on this machine; works
 kraftwerk devices                       # paired devices (a phone, another computer); devices pair|revoke
 kraftwerk remote on|off|pair            # reach this machine from anywhere through the relay, end to end encrypted
 kraftwerk projects                      # goal-scoped project folders; projects create|show|link|log|remove
+kraftwerk boards|tasks                  # task boards per project or workspace; tasks create|show|move|assign|log|pick|remove
 kraftwerk contacts|places|events        # who, where and when, one Markdown file each; … show|create|set|remove, events --from/--to
 kraftwerk ref <kind:slug>               # resolve a reference (contact:anna-meier, project:relaunch, …); --file <md> resolves every one in a file
 kraftwerk trash                         # what was deleted; trash restore|purge <id>, trash empty
@@ -300,7 +301,9 @@ Optional, at the project root, and also the root marker for the walk-up. All
 fields are optional. `workflows:` sets the workflows root, `output:` the
 run-artifact directory (default `output/`), `knowledge:` the OKF bundle root
 (default `knowledge/`), and `agents:` the agent-definition root (default
-`agents/`). `repos:` turns on the [repositories](#repositories) folder.
+`agents/`). `repos:` turns on the [repositories](#repositories) folder,
+`projects:` the [projects](#projects), and `contacts:`, `places:` and
+`events:` each one of the [contacts, places and events](#contacts-places-and-events).
 `cloud: { enabled: false }` leaves the workspace out of this machine's
 record in the [kraftwerk cloud](#this-machine-in-the-kraftwerk-cloud).
 
@@ -342,7 +345,8 @@ projects (all but archived ones) and the channels of every workspace on this
 machine, grouped by workspace and running or not (a stopped one is started
 on the way), read from the workspace registry under `~/.kraftwerk/workspaces`,
 which every inspector keeps current with its roster, project and channel
-lists.
+lists — and this workspace's contacts, places and events, by title, role,
+organisation, address or date.
 
 ### Triggering from CI, cron, or webhooks
 
@@ -631,6 +635,57 @@ kraftwerk projects remove relaunch-netnode-ch
 The registry of workspaces on this machine, which answered to
 `kraftwerk projects` until 0.48, is `kraftwerk workspaces` now.
 
+## Boards and tasks
+
+Turn on `boards:` in `kraftwerk.yml` (or the checkbox in settings) and every
+project can have task boards, and the workspace its own:
+
+```yaml
+boards:
+  root: kraftwerk-data/boards   # default; the workspace's boards (a project's live in projects/<slug>/boards/)
+  columns: [draft, todo, progress, review, done]   # default for boards that name none
+```
+
+```
+projects/<slug>/boards/<board>/board.md            # title, columns, default agent, stale_after + the board's rules
+projects/<slug>/boards/<board>/tasks/<n>-<slug>/   # one task: task.md, log.md, its files
+kraftwerk-data/boards/<board>/…                    # workspace boards, same shape
+```
+
+A column is a slug or `{slug, label, limit, done, review}`: `review: true`
+means tasks there wait for a human (they count as attention), `done: true`
+means finished. The column is a field of `task.md`, so a move is a one-line
+diff and the task's folder never moves. Task folders are numbered per board
+(`50-write-a-press-release`); the number names the task in the CLI, the
+folder name is its reference (`task:50-write-a-press-release`). The log is in
+the journal format: `## 2026-11-05` days, `* 16:40 Moved Todo → In progress:
+starting (lisa/claude)` lines, newest first; kraftwerk writes it on every
+create, move, assign, pick and file change, and agents and humans add lines.
+
+```
+kraftwerk boards [--project <p>] [--all]            # the boards; boards show|create|set|remove
+kraftwerk tasks [--project <p>] [--board <b>]       # the tasks of a board (default: the project's `tasks` board)
+kraftwerk tasks create "<title>" --status todo --assign lisa --file $KRAFTWERK_TEMP/task.md -m "…"
+kraftwerk tasks show 50 | move 50 review -m "…" | assign 50 max -m "…" | assign 50 human | log 50 "…" | pick --as lisa | remove 50
+```
+
+**Agents and the board.** A project chat and every agent see the boards
+in their context: columns with counts, the open tasks, the rules written
+in `board.md`, and the commands. Inside a session the CLI knows who it is
+(`KRAFTWERK_AGENT`, `KRAFTWERK_ACTOR`), so `tasks pick` and `tasks log` need
+no name. Waking is event-based: whenever a task has an agent as assignee
+and sits in a work column — created there, moved there, assigned, handed
+over — that agent gets a session with the task as its scope (the task
+block: `task.md`, the files, the whole log, so a hand-over reads like a
+message from the previous agent), or the message is posted into its open
+session for that task. Draft, Review and Done never wake anyone; an agent
+acting on its own task does not wake itself; a board's `agent:` is the
+default assignee for tasks entering Todo unassigned. The events are lines in
+`<output>/boards/events.jsonl`, local to the machine, so a clone of the
+workspace never starts the same work twice. Only a human moves a task into a
+done column; `tasks assign <n> human` clears the assignee and puts the task
+into Review.
+
 ## Contacts, places and events
 
 Who, where and when, kept by the workspace itself so people and agents can

package/dist/cli/boards.d.ts

@@ -0,0 +1,2 @@
+import type { Command } from "commander";
+export declare function registerBoardCommands(program: Command): void;

package/dist/cli/boards.js

@@ -0,0 +1,486 @@
+import chalk from "chalk";
+import Table from "cli-table3";
+import { readFile } from "node:fs/promises";
+import { appendTaskLog, assignTask, createBoard, createTask, DEFAULT_BOARD, deleteBoard, deleteTask, ensureDefaultBoard, getBoard, getTask, listAllBoards, listBoards, moveTask, pickTask, saveBoard, saveTask, } from "../core/boards.js";
+import { taskSessions } from "../core/board-wake.js";
+import { initContext as prepare } from "./routines.js";
+import { fmtAgo } from "./workspaces.js";
+/**
+ * `kraftwerk boards` and `kraftwerk tasks` — the boards (columns of tasks)
+ * of a project or of the workspace, and the tasks on them. The same module
+ * the inspector uses, so a task created here is on the board at once, and
+ * the agent that is assigned is woken by the server. An agent inside a
+ * session needs no --as: KRAFTWERK_AGENT names it, KRAFTWERK_ACTOR signs
+ * its log lines.
+ *
+ *   kraftwerk boards [--project <p>] [--all]                   list boards (the workspace's, a project's, every one)
+ *   kraftwerk boards show <board> [--project <p>]              columns, rules, the tasks per column
+ *   kraftwerk boards create <title> [--project <p>] [--agent]  new board with the default columns
+ *   kraftwerk boards set <board> --agent <slug> | --notes-file  change default agent, stale_after, rules
+ *   kraftwerk boards remove <board>                            move the board to the trash
+ *
+ *   kraftwerk tasks [--board <b>] [--project <p>] [--status] [--assignee] [--mine]
+ *   kraftwerk tasks show <n>                                   task.md, folder path, files, log
+ *   kraftwerk tasks create <title> [--status todo] [--assign <agent>] [--file task.md] [-m]
+ *   kraftwerk tasks set <n> [--title] [--due] [--tags] [--refs] [--notes-file]
+ *   kraftwerk tasks move <n> <column> [-m "<why>"]
+ *   kraftwerk tasks assign <n> <agent> [-m "<hand-over note>"] | --to human
+ *   kraftwerk tasks log <n> "<what you did>" [--tail <k>]
+ *   kraftwerk tasks pick [--as <agent>] [--column todo]
+ *   kraftwerk tasks remove <n>
+ *
+ * --board defaults to the project's `tasks` board (or the only board); the
+ * number alone names a task.
+ */
+const die = (msg) => {
+    console.error(chalk.red(msg));
+    process.exit(1);
+};
+/** Who writes: --actor, else the session's KRAFTWERK_ACTOR, else human:user. */
+const actorOf = (opt) => (opt ?? process.env.KRAFTWERK_ACTOR ?? "").trim() || "human:user";
+/** Which agent acts: --as, else the session's KRAFTWERK_AGENT. */
+const agentOf = (opt) => (opt ?? process.env.KRAFTWERK_AGENT ?? "").trim();
+/** The board a command means: --board, else the project's default board when it exists, else the only board. */
+async function whereOf(w, create = false) {
+    const project = w.project?.trim() || undefined;
+    if (w.board)
+        return { ...(project ? { project } : {}), board: w.board.trim() };
+    const view = await listBoards(project);
+    if (!view.enabled)
+        die(view.error ?? "boards are off");
+    if (view.error)
+        die(view.error);
+    const dflt = view.boards.find((b) => b.board === DEFAULT_BOARD);
+    if (dflt)
+        return { ...(project ? { project } : {}), board: DEFAULT_BOARD };
+    if (view.boards.length === 1)
+        return { ...(project ? { project } : {}), board: view.boards[0].board };
+    if (create && view.boards.length === 0)
+        return ensureDefaultBoard(project);
+    if (view.boards.length === 0)
+        die(`no board ${project ? `in project ${project}` : "in the workspace"} yet — \`kraftwerk boards create "<title>"${project ? ` --project ${project}` : ""}\` makes one`);
+    return die(`several boards here (${view.boards.map((b) => b.board).join(", ")}) — say which with --board`);
+}
+const flags = (ref) => (ref.project ? `--project ${ref.project} --board ${ref.board}` : `--board ${ref.board}`);
+function taskRow(t) {
+    return [
+        chalk.cyan(String(t.number)),
+        t.configError ? chalk.red(t.configError) : t.title,
+        t.status,
+        t.assignee ?? chalk.dim("—"),
+        t.due ?? chalk.dim("—"),
+        chalk.dim(t.lastLog ?? ""),
+        chalk.dim(fmtAgo(t.updatedAt)),
+    ];
+}
+function printBoard(b) {
+    console.log(`${chalk.bold(b.title)} ${chalk.dim(`(${b.project ? `${b.project}/` : ""}${b.board}${b.agent ? `, default agent ${b.agent}` : ""})`)}`);
+    if (b.configError)
+        console.log(chalk.red(`board.md: ${b.configError}`));
+    if (b.notes.trim())
+        console.log(b.notes.trim());
+    console.log(chalk.dim(b.path));
+    for (const c of b.columns) {
+        const items = b.items.filter((t) => t.status === c.slug);
+        console.log(`\n${chalk.bold(c.label)} ${chalk.dim(`(${items.length}${c.limit ? `/${c.limit}` : ""}${c.review ? ", review" : c.done ? ", done" : ""})`)}`);
+        for (const t of items)
+            console.log(`  ${chalk.cyan(String(t.number).padStart(3))}  ${t.title}${t.assignee ? chalk.dim(` · ${t.assignee}`) : ""}${t.due ? chalk.dim(` · due ${t.due}`) : ""}${t.stale ? chalk.yellow(" · stale") : ""}`);
+    }
+    const lost = b.items.filter((t) => !b.columns.some((c) => c.slug === t.status));
+    if (lost.length) {
+        console.log(`\n${chalk.bold("no column")}`);
+        for (const t of lost)
+            console.log(`  ${chalk.cyan(String(t.number).padStart(3))}  ${t.title} ${chalk.dim(`(status "${t.status}")`)}`);
+    }
+}
+function printTask(t) {
+    console.log(`${chalk.cyan(String(t.number))} ${chalk.bold(t.title)} ${chalk.dim(`(${t.ref})`)}`);
+    console.log(`${t.status}${t.assignee ? ` · ${t.assignee}` : " · unassigned"}${t.due ? ` · due ${t.due}` : ""}${t.tags.length ? ` · ${t.tags.join(", ")}` : ""}${t.stale ? chalk.yellow(" · stale") : ""}`);
+    if (t.refs.length)
+        console.log(chalk.dim(`refs: ${t.refs.join(", ")}`));
+    console.log(chalk.dim(`folder: ${t.path}`));
+    const sessions = t.sessions ?? [];
+    if (sessions.length)
+        console.log(chalk.dim(`sessions: ${sessions.map((s) => `${s.emoji ? `${s.emoji} ` : ""}${s.name ?? s.agent} ${s.id}${s.busy ? " (working)" : ""}`).join(", ")}`));
+    if (t.configError)
+        console.log(chalk.red(`task.md: ${t.configError}`));
+    if (t.notes.trim())
+        console.log(`\n${t.notes.trim()}`);
+    console.log(`\n${chalk.bold("files")}${t.fileList.length ? "" : chalk.dim(" (none)")}`);
+    for (const f of t.fileList)
+        console.log(`  ${f}`);
+    if (t.log.trim())
+        console.log(`\n${chalk.bold("log")}\n${t.log.trim()}`);
+}
+export function registerBoardCommands(program) {
+    const boards = program.command("boards").description("Task boards of a project or the workspace: list, show, create, set, remove");
+    boards
+        .command("list", { isDefault: true })
+        .description("List the boards: the workspace's, a project's (--project), or every one (--all)")
+        .option("--project <slug>", "A project's boards")
+        .option("--all", "Every board of the workspace and its projects")
+        .option("--json", "Machine-readable output")
+        .action(async (opts) => {
+        await prepare();
+        const view = opts.all ? { enabled: true, boards: await listAllBoards() } : await listBoards(opts.project);
+        if (opts.json) {
+            console.log(JSON.stringify(view, null, 2));
+            return;
+        }
+        if (!view.enabled)
+            die(("error" in view && view.error) || "boards are off");
+        if ("error" in view && view.error)
+            die(view.error);
+        if (view.boards.length === 0) {
+            console.log(chalk.dim(`No boards ${opts.project ? `in project ${opts.project}` : opts.all ? "anywhere" : "in the workspace"} yet — \`kraftwerk boards create "<title>"${opts.project ? ` --project ${opts.project}` : ""}\` starts one.`));
+            return;
+        }
+        const table = new Table({ head: ["board", "where", "tasks", "review", "columns", "changed"].map((h) => chalk.bold(h)) });
+        for (const b of view.boards) {
+            table.push([
+                `${chalk.cyan(b.title)}\n${chalk.dim(b.board)}`,
+                b.project ? `project ${b.project}` : chalk.dim("workspace"),
+                String(b.tasks),
+                b.review ? chalk.yellow(String(b.review)) : chalk.dim("0"),
+                chalk.dim(b.configError ? chalk.red(b.configError) : b.columns.map((c) => `${c.label} ${b.counts[c.slug] ?? 0}`).join(" · ")),
+                chalk.dim(fmtAgo(b.updatedAt)),
+            ]);
+        }
+        console.log(table.toString());
+    });
+    boards
+        .command("show")
+        .description("One board: columns, rules, every task per column")
+        .argument("<board>", "Board slug")
+        .option("--project <slug>", "The project the board belongs to")
+        .option("--json", "Machine-readable output")
+        .action(async (board, opts) => {
+        await prepare();
+        try {
+            const b = await getBoard({ ...(opts.project ? { project: opts.project } : {}), board });
+            if (!b)
+                die(`no board "${board}"`);
+            if (opts.json)
+                console.log(JSON.stringify(b, null, 2));
+            else
+                printBoard(b);
+        }
+        catch (err) {
+            die(err.message);
+        }
+    });
+    boards
+        .command("create")
+        .description("Create a board with the default columns (draft, todo, progress, review, done) unless --columns is given")
+        .argument("<title>", "Display title; the folder name is derived from it unless --slug is given")
+        .option("--project <slug>", "Create it inside this project (projects/<slug>/boards/)")
+        .option("--slug <slug>", "Folder name (lowercase, digits, dashes)")
+        .option("--columns <list>", "Comma-separated column slugs")
+        .option("--agent <slug>", "Default agent: tasks entering todo unassigned go to it")
+        .option("--notes <text>", "The board's rules (the body of board.md)")
+        .option("--json", "Print the board as JSON")
+        .action(async (title, opts) => {
+        await prepare();
+        try {
+            const b = await createBoard({ project: opts.project, title, slug: opts.slug, columns: opts.columns ? opts.columns.split(",").map((s) => s.trim()).filter(Boolean) : undefined, agent: opts.agent, notes: opts.notes });
+            if (opts.json)
+                console.log(JSON.stringify(b, null, 2));
+            else
+                console.log(`${chalk.green("✔")} ${chalk.cyan(b.board)} → ${b.path} ${chalk.dim(`(columns: ${b.columns.map((c) => c.slug).join(", ")})`)}`);
+        }
+        catch (err) {
+            die(err.message);
+        }
+    });
+    boards
+        .command("set")
+        .description("Change a board's title, default agent, stale_after or rules")
+        .argument("<board>", "Board slug")
+        .option("--project <slug>", "The project the board belongs to")
+        .option("--title <text>", "Display title")
+        .option("--agent <slug>", 'Default agent; "" clears it')
+        .option("--stale-after <duration>", 'Mark a worked task stale after e.g. 12h, 2d; "" for the default (1d)')
+        .option("--columns <list>", "Comma-separated column slugs (replaces the list)")
+        .option("--notes-file <path>", "Replace the rules with this file's text")
+        .option("--json", "Print the board as JSON")
+        .action(async (board, opts) => {
+        await prepare();
+        try {
+            const input = {
+                ...(opts.title !== undefined ? { title: opts.title } : {}),
+                ...(opts.agent !== undefined ? { agent: opts.agent || null } : {}),
+                ...(opts.staleAfter !== undefined ? { staleAfter: opts.staleAfter || null } : {}),
+                ...(opts.columns !== undefined ? { columns: opts.columns.split(",").map((s) => s.trim()).filter(Boolean) } : {}),
+                ...(opts.notesFile ? { notes: await readFile(opts.notesFile, "utf8") } : {}),
+            };
+            if (Object.keys(input).length === 0)
+                die("nothing to set — pass --title, --agent, --stale-after, --columns or --notes-file");
+            const b = await saveBoard({ ...(opts.project ? { project: opts.project } : {}), board }, input);
+            if (opts.json)
+                console.log(JSON.stringify(b, null, 2));
+            else
+                console.log(`${chalk.green("✔")} ${chalk.cyan(b.board)} saved`);
+        }
+        catch (err) {
+            die(err.message);
+        }
+    });
+    boards
+        .command("remove")
+        .description("Move a board, tasks and all, to the trash")
+        .argument("<board>", "Board slug")
+        .option("--project <slug>", "The project the board belongs to")
+        .action(async (board, opts) => {
+        await prepare();
+        try {
+            await deleteBoard({ ...(opts.project ? { project: opts.project } : {}), board });
+            console.log(`${chalk.green("✔")} moved ${chalk.cyan(board)} to the trash`);
+        }
+        catch (err) {
+            die(err.message);
+        }
+    });
+    const tasks = program.command("tasks").description("Tasks on a board: list, show, create, set, move, assign, log, pick, remove");
+    const where = (cmd) => cmd.option("--board <slug>", "The board (default: the project's `tasks` board, or the only one)").option("--project <slug>", "The project the board belongs to");
+    where(tasks.command("list", { isDefault: true }))
+        .description("List the tasks of a board, column by column")
+        .option("--status <column>", "Only this column")
+        .option("--assignee <agent>", 'Only this agent\'s ("" for unassigned)')
+        .option("--mine", "Only the tasks of the agent this session runs as (KRAFTWERK_AGENT)")
+        .option("--as <agent>", "With --mine: which agent")
+        .option("--json", "Machine-readable output")
+        .action(async (opts) => {
+        await prepare();
+        try {
+            const ref = await whereOf(opts);
+            const b = await getBoard(ref);
+            if (!b)
+                die(`no board "${ref.board}"`);
+            const me = opts.mine ? agentOf(opts.as) || die("--mine needs --as <agent> outside an agent session") : undefined;
+            const items = b.items.filter((t) => (opts.status === undefined || t.status === opts.status) && (opts.assignee === undefined || (t.assignee ?? "") === opts.assignee) && (me === undefined || t.assignee === me));
+            if (opts.json) {
+                console.log(JSON.stringify({ board: ref, columns: b.columns, items }, null, 2));
+                return;
+            }
+            if (items.length === 0) {
+                console.log(chalk.dim(`No tasks on ${b.title}${opts.status ? ` in ${opts.status}` : ""}.`));
+                return;
+            }
+            const table = new Table({ head: ["#", "task", "column", "assignee", "due", "last", "changed"].map((h) => chalk.bold(h)), wordWrap: true, colWidths: [5, 36, 11, 12, 12, 30, 12] });
+            for (const t of items)
+                table.push(taskRow(t));
+            console.log(table.toString());
+            console.log(chalk.dim(`${b.title} (${flags(ref)})`));
+        }
+        catch (err) {
+            die(err.message);
+        }
+    });
+    where(tasks.command("show"))
+        .description("One task: fields, markdown, folder path, files and log")
+        .argument("<task>", "Task number or folder name")
+        .option("--json", "Machine-readable output")
+        .action(async (task, opts) => {
+        await prepare();
+        try {
+            const found = await getTask(await whereOf(opts), task);
+            if (!found)
+                die(`no task "${task}"`);
+            const t = { ...found, sessions: await taskSessions(found.ref).catch(() => []) };
+            if (opts.json)
+                console.log(JSON.stringify(t, null, 2));
+            else
+                printTask(t);
+        }
+        catch (err) {
+            die(err.message);
+        }
+    });
+    where(tasks.command("create"))
+        .description("Create a task (a numbered folder with task.md and log.md); --assign with --status todo wakes the agent")
+        .argument("<title>", "The task's title")
+        .option("--status <column>", "The column it starts in (default: the first, draft)")
+        .option("--assign <agent>", "Assignee (an agent slug)")
+        .option("--due <date>", "Due date, 2026-11-20")
+        .option("--tags <list>", "Comma-separated tags")
+        .option("--refs <list>", "Comma-separated kind:slug references (contact:anna-meier, knowledge:brand-voice)")
+        .option("--file <path>", "The task's markdown (what, done-when, notes) from a file")
+        .option("--notes <text>", "The task's markdown inline")
+        .option("-m, --message <text>", "A first log line")
+        .option("--actor <actor>", "Who writes (default: KRAFTWERK_ACTOR, else human:user)")
+        .option("--json", "Print the task as JSON")
+        .action(async (title, opts) => {
+        await prepare();
+        try {
+            const ref = await whereOf(opts, true);
+            const t = await createTask(ref, {
+                title,
+                status: opts.status,
+                assignee: opts.assign,
+                due: opts.due,
+                tags: opts.tags,
+                refs: opts.refs,
+                notes: opts.file ? await readFile(opts.file, "utf8") : opts.notes,
+                actor: actorOf(opts.actor),
+                message: opts.message,
+            });
+            if (opts.json)
+                console.log(JSON.stringify(t, null, 2));
+            else
+                console.log(`${chalk.green("✔")} ${chalk.cyan(String(t.number))} ${t.title} ${chalk.dim(`(${t.status}${t.assignee ? `, ${t.assignee}` : ""}) → ${t.path}`)}`);
+        }
+        catch (err) {
+            die(err.message);
+        }
+    });
+    where(tasks.command("set"))
+        .description("Change a task's title, due date, tags, refs or markdown")
+        .argument("<task>", "Task number or folder name")
+        .option("--title <text>", "New title (the folder keeps its name)")
+        .option("--due <date>", 'Due date; "" clears it')
+        .option("--tags <list>", "Comma-separated tags (replaces)")
+        .option("--refs <list>", "Comma-separated kind:slug references (replaces)")
+        .option("--notes-file <path>", "Replace the markdown with this file's text")
+        .option("--actor <actor>", "Who writes")
+        .option("--json", "Print the task as JSON")
+        .action(async (task, opts) => {
+        await prepare();
+        try {
+            const input = {
+                ...(opts.title !== undefined ? { title: opts.title } : {}),
+                ...(opts.due !== undefined ? { due: opts.due || null } : {}),
+                ...(opts.tags !== undefined ? { tags: opts.tags } : {}),
+                ...(opts.refs !== undefined ? { refs: opts.refs } : {}),
+                ...(opts.notesFile ? { notes: await readFile(opts.notesFile, "utf8") } : {}),
+            };
+            if (Object.keys(input).length === 0)
+                die("nothing to set — pass --title, --due, --tags, --refs or --notes-file");
+            const t = await saveTask(await whereOf(opts), task, input, { actor: actorOf(opts.actor) });
+            if (opts.json)
+                console.log(JSON.stringify(t, null, 2));
+            else
+                console.log(`${chalk.green("✔")} ${chalk.cyan(String(t.number))} ${t.title} saved`);
+        }
+        catch (err) {
+            die(err.message);
+        }
+    });
+    where(tasks.command("move"))
+        .description("Put a task into a column; the move is logged with -m, and an assigned agent entering a work column is woken")
+        .argument("<task>", "Task number or folder name")
+        .argument("<column>", "Column slug")
+        .option("-m, --message <text>", "Why, for the log")
+        .option("--actor <actor>", "Who writes")
+        .option("--json", "Print the task as JSON")
+        .action(async (task, column, opts) => {
+        await prepare();
+        try {
+            const t = await moveTask(await whereOf(opts), task, column, { message: opts.message, actor: actorOf(opts.actor) });
+            if (opts.json)
+                console.log(JSON.stringify(t, null, 2));
+            else
+                console.log(`${chalk.green("✔")} ${chalk.cyan(String(t.number))} ${t.title} → ${t.status}`);
+        }
+        catch (err) {
+            die(err.message);
+        }
+    });
+    where(tasks.command("assign"))
+        .description('Hand a task to an agent (woken when the task is in a work column), or back to the humans with "human" (unassigned, into review)')
+        .argument("<task>", "Task number or folder name")
+        .argument("[agent]", 'Agent slug, or "human"; omit with --to')
+        .option("--to <agent>", 'Same as the argument: an agent slug or "human"')
+        .option("-m, --message <text>", "The hand-over note, for the log and the next agent")
+        .option("--actor <actor>", "Who writes")
+        .option("--json", "Print the task as JSON")
+        .action(async (task, agent, opts) => {
+        await prepare();
+        const to = (opts.to ?? agent ?? "").trim();
+        if (!to)
+            die('say who: `tasks assign <n> <agent>` or `--to human`');
+        try {
+            const t = await assignTask(await whereOf(opts), task, to === "human" ? null : to, { message: opts.message, actor: actorOf(opts.actor) });
+            if (opts.json)
+                console.log(JSON.stringify(t, null, 2));
+            else
+                console.log(`${chalk.green("✔")} ${chalk.cyan(String(t.number))} ${t.title} → ${t.assignee ?? `humans (${t.status})`}`);
+        }
+        catch (err) {
+            die(err.message);
+        }
+    });
+    where(tasks.command("log"))
+        .description("Append a stamped line to the task's log (what you did, a question, a decision), or print the last lines with --tail")
+        .argument("<task>", "Task number or folder name")
+        .argument("[entry]", "The line to record")
+        .option("--file <path>", "Read the entry from a file")
+        .option("--tail <n>", "Print the newest n lines instead of writing")
+        .option("--actor <actor>", "Who writes (default: KRAFTWERK_ACTOR, else human:user)")
+        .action(async (task, entry, opts) => {
+        await prepare();
+        try {
+            const ref = await whereOf(opts);
+            if (opts.tail !== undefined) {
+                const t = await getTask(ref, task);
+                if (!t)
+                    die(`no task "${task}"`);
+                const n = Number(opts.tail) || 5;
+                console.log(t.log
+                    .split("\n")
+                    .filter((l) => l.startsWith("* ") || l.startsWith("## "))
+                    .slice(0, n * 2)
+                    .join("\n"));
+                return;
+            }
+            const text = opts.file ? await readFile(opts.file, "utf8") : entry ?? "";
+            const t = await appendTaskLog(ref, task, text, actorOf(opts.actor));
+            console.log(`${chalk.green("✔")} logged on ${chalk.cyan(String(t.number))} ${chalk.dim(`(${actorOf(opts.actor)})`)}`);
+        }
+        catch (err) {
+            die(err.message);
+        }
+    });
+    where(tasks.command("pick"))
+        .description("Take the next task of the pick column (todo): it becomes yours and moves to the work column; prints nothing and exits 3 when there is none")
+        .option("--as <agent>", "Which agent picks (default: KRAFTWERK_AGENT)")
+        .option("--column <slug>", "Pick from this column instead of todo")
+        .option("--json", "Print the task as JSON")
+        .action(async (opts) => {
+        await prepare();
+        const agent = agentOf(opts.as);
+        if (!agent)
+            die("who picks? pass --as <agent> (inside an agent session KRAFTWERK_AGENT is set)");
+        try {
+            const t = await pickTask(await whereOf(opts), agent, { column: opts.column, actor: process.env.KRAFTWERK_ACTOR || agent });
+            if (!t) {
+                if (opts.json)
+                    console.log("null");
+                else
+                    console.log(chalk.dim("nothing to pick"));
+                process.exit(3);
+            }
+            if (opts.json)
+                console.log(JSON.stringify(t, null, 2));
+            else {
+                console.log(`${chalk.green("✔")} picked ${chalk.cyan(String(t.number))} ${t.title} → ${t.status}`);
+                printTask(t);
+            }
+        }
+        catch (err) {
+            die(err.message);
+        }
+    });
+    where(tasks.command("remove"))
+        .description("Move a task folder, files and log included, to the trash")
+        .argument("<task>", "Task number or folder name")
+        .action(async (task, opts) => {
+        await prepare();
+        try {
+            await deleteTask(await whereOf(opts), task);
+            console.log(`${chalk.green("✔")} moved task ${chalk.cyan(task)} to the trash`);
+        }
+        catch (err) {
+            die(err.message);
+        }
+    });
+}

package/dist/cli/init.js

@@ -34,6 +34,7 @@ skills: ${DATA_DIR}/skills         # workspace skills (shared instruction packag
 # contacts:                       # people and organisations, one Markdown file each under ${DATA_DIR}/contacts — referenced as contact:<slug> (uncomment to enable)
 # places:                         # addresses and points of interest, one Markdown file each under ${DATA_DIR}/places — referenced as place:<slug> (uncomment to enable)
 # events:                         # dated one-off entries with place, contacts and project, one Markdown file each under ${DATA_DIR}/events — referenced as event:<slug> (uncomment to enable)
+# boards:                         # tasks as folders in columns (Draft, Todo, In progress, Review, Done) per project and under ${DATA_DIR}/boards — agents are woken when a task is assigned to them (uncomment to enable)
 # cloud:                          # the daemon registers this MACHINE with the kraftwerk cloud and lists this workspace (\`kraftwerk login\` claims the machine)
 #   enabled: false                # uncomment both lines to leave this workspace out (\`kraftwerk cloud off\` turns the cloud off for the whole machine)
 `;
@@ -139,11 +140,12 @@ export async function runInit(cwd) {
         created.push(bundleRel);
     }
     // .gitignore: the output dir, the repos root (clones must never become
-    // gitlinks of the workspace repo) and .env (secrets). A missing file gets
+    // gitlinks of the workspace repo), the temp root (session scratch, which
+    // also carries a .gitignore of its own) and .env (secrets). A missing file gets
     // all in one write; an existing one only the entries it lacks.
     const gitignorePath = path.join(cwd, ".gitignore");
     const gitignore = (await readFile(gitignorePath, "utf8").catch(() => null)) ?? null;
-    const entries = [`${DATA_DIR}/output/`, `${DATA_DIR}/repos/`, DOTENV_FILE];
+    const entries = [`${DATA_DIR}/output/`, `${DATA_DIR}/repos/`, `${DATA_DIR}/temp/`, DOTENV_FILE];
     if (gitignore === null) {
         await writeFile(gitignorePath, entries.map((e) => `${e}\n`).join(""));
         created.push(".gitignore");

package/dist/cli/kraftwerk.js

@@ -13,11 +13,13 @@ import { runDoctor } from "./doctor.js";
 import { runInit } from "./init.js";
 import { registerKnowledgeCommands } from "./knowledge.js";
 import { registerProjectCommands } from "./projects.js";
+import { registerBoardCommands } from "./boards.js";
 import { registerContactCommands, registerEventCommands, registerPlaceCommands, registerRefCommand } from "./entities.js";
 import { registerWorkspaceCommands } from "./workspaces.js";
 import { registerRepoCommands } from "./repos.js";
 import { registerVibeableCommands } from "./vibeables.js";
 import { registerTrashCommands } from "./trash.js";
+import { registerTempCommands } from "./temp.js";
 import { registerDevicesCommands } from "./devices.js";
 import { registerDaemonCommand } from "./daemon.js";
 import { registerRemoteCommand } from "./remote.js";
@@ -43,12 +45,14 @@ import { runUi } from "./ui.js";
  *   kraftwerk ui                      start the inspector web UI (localhost:1981)
  *   kraftwerk workspaces ...          known workspaces on this machine (list/start/stop/forget)
  *   kraftwerk projects ...            goal-scoped project folders (list/create/show/link/log/remove)
+ *   kraftwerk boards|tasks ...        task boards per project or workspace: list/show/create; tasks list/show/create/move/assign/log/pick/remove
  *   kraftwerk contacts|places|events  who, where and when: one Markdown file each (list/show/create/set/remove)
  *   kraftwerk ref <kind:slug>         resolve a reference (contact:anna-meier) or every one in a file
  *   kraftwerk vibeables ...           small apps built live in a chat (list/create/remove)
  *   kraftwerk repos ...               repositories the agents work on (list/add/update/remove)
  *   kraftwerk journal <agent> [entry] an agent's memory across sessions: print it, add a line
  *   kraftwerk trash ...               what was deleted: list, restore, purge, empty
+ *   kraftwerk temp [clean]            the sessions' scratch folders (TMPDIR of every agent): list, clean
  *   kraftwerk devices ...             paired devices: list, pair one, revoke one
  *   kraftwerk daemon                  the machine's kraftwerk: every open workspace at <slug>.localhost
  *   kraftwerk cloud [on|off|status]   this machine in the kraftwerk cloud (the daemon registers it)
@@ -302,6 +306,7 @@ registerKnowledgeCommands(program);
 registerRoutineCommands(program);
 registerWorkspaceCommands(program);
 registerProjectCommands(program);
+registerBoardCommands(program);
 registerContactCommands(program);
 registerPlaceCommands(program);
 registerEventCommands(program);
@@ -309,6 +314,7 @@ registerRefCommand(program);
 registerRepoCommands(program);
 registerVibeableCommands(program);
 registerTrashCommands(program);
+registerTempCommands(program);
 registerDevicesCommands(program);
 registerDaemonCommand(program);
 registerRemoteCommand(program);

package/dist/cli/temp.d.ts

@@ -0,0 +1,2 @@
+import type { Command } from "commander";
+export declare function registerTempCommands(program: Command): void;