@pi-unipi/kanboard 3.0.0-alpha.16 → 3.0.0-alpha.17

package/index.ts

@@ -416,6 +416,10 @@ export default function (pi: ExtensionAPI) {
     // cannot release), and release requires a comment — the next run's resume
     // notice keys on it. Best effort: a dead pid is reaped with "session
     // lost" anyway.
+    // Children (subagents, fusion sidekicks, kanboard's own helpers) inherit
+    // the lead's session id: their shutdown must never release the lead's
+    // claims (a finished subagent used to bounce the lead's task to Todo).
+    if (isChildProcess() || process.env.UNIPI_KANBOARD_CHILD) return;
     try {
       const session = sessionId();
       const claims = await ownClaims();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-unipi/kanboard",
-  "version": "3.0.0-alpha.16",
+  "version": "3.0.0-alpha.17",
   "description": "Kanboard v3 — deferred-work board: CLI/daemon bridge, task runner and skill",
   "type": "module",
   "main": "index.ts",
@@ -31,7 +31,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@pi-unipi/core": "3.0.0-alpha.16"
+    "@pi-unipi/core": "3.0.0-alpha.17"
   },
   "peerDependencies": {
     "@earendil-works/pi-coding-agent": "^0.87.1",
@@ -48,10 +48,10 @@
     "themes": []
   },
   "optionalDependencies": {
-    "@pi-unipi/kanboard-linux-x64": "3.0.0-alpha.16",
-    "@pi-unipi/kanboard-linux-arm64": "3.0.0-alpha.16",
-    "@pi-unipi/kanboard-darwin-x64": "3.0.0-alpha.16",
-    "@pi-unipi/kanboard-darwin-arm64": "3.0.0-alpha.16",
-    "@pi-unipi/kanboard-win32-x64": "3.0.0-alpha.16"
+    "@pi-unipi/kanboard-linux-x64": "3.0.0-alpha.17",
+    "@pi-unipi/kanboard-linux-arm64": "3.0.0-alpha.17",
+    "@pi-unipi/kanboard-darwin-x64": "3.0.0-alpha.17",
+    "@pi-unipi/kanboard-darwin-arm64": "3.0.0-alpha.17",
+    "@pi-unipi/kanboard-win32-x64": "3.0.0-alpha.17"
   }
 }

package/skills/kanboard/SKILL.md

@@ -22,13 +22,13 @@ be on `PATH`):
 <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> start <ID>                          # todo → in progress, claimed for your session (costs a -do slot)
-<binary> --actor agent --project <slug> finish <ID> --comment "<summary>"   # in progress → in review, only a task you started (free)
-<binary> --actor agent --project <slug> move <ID> blocked --comment "<what you need>"
+<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>
@@ -94,9 +94,8 @@ lists them — read the files there directly if you need one.
    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. **Sidekicks and subagents can read the board but never write it** — every
@@ -106,7 +105,14 @@ lists them — read the files there directly if you need one.
    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.
@@ -126,6 +132,9 @@ but only to write a summary.)
 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/commands.ts

@@ -44,7 +44,7 @@ Priority -p: 1 none · 2 low · 3 medium · 4 high · 5 urgent`;
 export function doText(slug: string, cli: string, request: string, slots = DEFAULT_DO_TASKS, writes = DEFAULT_DO_WRITES): string {
   const s = slots === 1 ? "" : "s";
   const ws = writes === 1 ? "" : "s";
-  return `[kanboard] For this request you may use the kanboard skill on project ${slug} (CLI: \`${cli} --actor agent --project ${slug} …\`). Budget this session: ${String(slots)} task slot${s} — each \`start\` uses one — and ${String(writes)} board write${ws} (add, edit, link, order, move backlog↔todo, note on tasks you don't hold); /unipi:kanboard-do tops both back up. Always free: reads, and \`finish\`, \`move <ID> blocked --comment\` and \`note\` on tasks you started. Work the tasks yourself in this session, in whatever mode fits: \`start <ID>\` right before you work it, then \`finish <ID> --comment "<summary>"\` or \`move <ID> blocked --comment "<what you need>"\` — never leave a task you started In Progress. Before starting anything, count the tasks this request needs; if that is more than ${String(slots)}, start nothing — tell me you can do ${String(slots)} now and ask whether to raise the limit (setting kanboard.doTasks) or work in batches. Read a task with \`show <ID>\` before editing or starting it — \`list\` only shows titles and a one-line excerpt. Sidekicks and subagents can read the board but not write it: brief them with the task, then update the board yourself from their report. If the request is unclear, ask me instead of guessing.
+  return `[kanboard] For this request you may use the kanboard skill on project ${slug} (CLI: \`${cli} --actor agent --project ${slug} …\`). Budget this session: ${String(slots)} task slot${s} — each \`start\` uses one — and ${String(writes)} board write${ws} (add, edit, link, order, move backlog↔todo, note on tasks you don't hold); /unipi:kanboard-do tops both back up. Always free: reads, and \`finish\`, \`move <ID> blocked --comment\`, \`note\` and \`attach\` on tasks you started. Work the tasks yourself in this session, in whatever mode fits: \`start <ID>\` right before you work it, then \`finish <ID> --comment "<summary>"\` or \`move <ID> blocked --comment "<what you need>"\` — never leave a task you started In Progress. Before starting anything, count the tasks this request needs; if that is more than ${String(slots)}, start nothing — tell me you can do ${String(slots)} now and ask whether to raise the limit (setting kanboard.doTasks) or work in batches. Read a task with \`show <ID>\` before editing or starting it — \`list\` only shows titles and a one-line excerpt. Sidekicks and subagents can read the board but not write it: brief them with the task, then update the board yourself from their report. If the request is unclear, ask me instead of guessing.
 
 Request: ${request}`;
 }

package/src/guard.ts

@@ -5,7 +5,7 @@
  * writes. A `/unipi:kanboard-do` grants task SLOTS (each `start` uses one)
  * and a WRITE budget (add, edit, link, order, move backlog↔todo, note on
  * tasks you don't hold). Always free: reads, and `finish`, `move <ID>
- * blocked` and `note <ID>` on claims this session started — a started task
+ * blocked`, `note <ID>` and `attach <ID>` on claims this session started — a started task
  * can always be closed. Autowork lifts both budgets (the runaway guard is
  * the per-turn add cap). In child processes every write is refused: the
  * lead updates the board.
@@ -282,9 +282,9 @@ export function createWriteGuard(options: WriteGuardOptions = {}): WriteGuard {
 					const id = firstPositional(invocation)!;
 					if (await ownsClaim(id)) continue; // closing your own claim is free
 				}
-				if (invocation.sub === "note" && firstPositional(invocation) !== undefined) {
+				if ((invocation.sub === "note" || invocation.sub === "attach") && firstPositional(invocation) !== undefined) {
 					const id = firstPositional(invocation)!;
-					if (await ownsClaim(id)) continue; // noting your own claim is free
+					if (await ownsClaim(id)) continue; // noting on / attaching to your own claim is free
 				}
 				if (autowork) continue; // autowork: unlimited slots and writes
 				if (invocation.sub === "start") {

package/src/settings.ts

@@ -34,12 +34,6 @@ export interface KanboardSettings {
   doTasks: number;
   /** Board writes a /unipi:kanboard-do grants. */
   doWrites: number;
-  /** Strategy for unlabelled tasks ("auto" = jev decides, gated by `jevThreshold`). */
-  defaultStrategy: "auto" | "none" | "goal" | "ralph" | "swarm" | "graph";
-  /** Confidence floor for jev's strategy answer; below it (or missing) the task runs "none". */
-  jevThreshold: number;
-  /** Plan-first for unlabelled tasks (jev is never asked about plan). */
-  defaultPlan: boolean;
   /** Whether a blocked-by-confusion task may ask the user (ask) or must
    *  assume-and-note (avoid, the default). */
   blocking: "avoid" | "ask";
@@ -62,9 +56,6 @@ export const DEFAULT_SETTINGS: KanboardSettings = {
   turnAddLimit: 20,
   doTasks: 5,
   doWrites: 10,
-  defaultStrategy: "none",
-  jevThreshold: 0.8,
-  defaultPlan: false,
   blocking: "avoid",
   reminders: true,
 };
@@ -162,16 +153,6 @@ export function readKanboardSettings(cwd: string = process.cwd()): KanboardSetti
       typeof raw.doWrites === "number" && raw.doWrites >= 0 && storedDoWritesSet(cwd)
         ? raw.doWrites
         : (storedLegacyDoCredits(cwd) ?? DEFAULT_SETTINGS.doWrites),
-    defaultStrategy:
-      typeof raw.defaultStrategy === "string" &&
-      ["auto", "none", "goal", "ralph", "swarm", "graph"].includes(raw.defaultStrategy)
-        ? (raw.defaultStrategy as KanboardSettings["defaultStrategy"])
-        : DEFAULT_SETTINGS.defaultStrategy,
-    jevThreshold:
-      typeof raw.jevThreshold === "number" && raw.jevThreshold > 0 && raw.jevThreshold <= 1
-        ? raw.jevThreshold
-        : DEFAULT_SETTINGS.jevThreshold,
-    defaultPlan: raw.defaultPlan === true,
     blocking: raw.blocking === "ask" ? "ask" : "avoid",
     reminders: raw.reminders !== false,
   };