takibibase 1.8.0 → 1.11.0

package/SKILL.md

@@ -38,8 +38,26 @@ error hints.
   `-k 1-12`, `--json`.
 - `takibi search -q "…"` — ranked chunks (snippets + metadata, not full
   text). Same flags, `-k 1-20`.
-- `takibi tasks list | get <id> | claim <id> | status <id> <todo|in_progress|review|done>`
-  and `takibi tasks artifact add <taskId> <url> [--note …]`.
+- `takibi tasks list | get <id> | claim <id> | status <id> <todo|in_progress|review|done> [--note …]`
+  and `takibi tasks artifact add <taskId> <url> [--note …]`. The status
+  `--note` is the review handoff note (max 1000 chars); leaving review
+  clears it.
+- `takibi tasks handoff <id> <profile> [--review] [--note "…"]` — hand a
+  card you hold to another profile on the same board (name or UUID; an
+  unknown name errors with the eligible names — never guess). Use
+  `--review` to move it to review in the same call and `--note` to leave
+  the review note with it: after the handoff you no longer hold the card,
+  so a follow-up `status` call would be refused. You cannot release a card
+  to nobody or hand on done/archived cards.
+- `@name` in a task names the handoff target: when your part is
+  finished, run `tasks handoff <id> name` (usually with `--review
+  --note`). The mention itself assigns nothing — the handoff does.
+- `takibi tasks escalate <id> --reason "…"` — ask the Founder for help
+  on a card you hold (reason required, max 500 chars; raising never
+  unassigns you). The flag clears on done, archive, or assignee change;
+  `takibi tasks deescalate <id>` retracts your flag ("never mind").
+  An orchestrator key can also clear any flag (audited) — treat that as
+  acknowledgment, not retraction.
 - `takibi doc list | get <id> | text <id>` — metadata, then converted text.
   `doc download` is account-only; the CLI says so — use `doc text`.
 - `takibi doc upload <file> [--project …] [--folder <uuid>]` — file one
@@ -128,10 +146,11 @@ abstains honestly instead of answering halfway.
 - Notes export/keep/remove need owner approval already given in the
   conversation. Export only creates a draft; verify it before adding
   content to Sources.
-- Task claim/status/artifact writes only with owner approval already
-  given in conversation. Claim-first: a plain key must claim a card before
+- Task claim/status/handoff/artifact/escalation writes only with owner approval
+  already given in conversation. Claim-first: a plain key must claim a card before
   moving or touching it; only orchestrators/owners accept (`review→done`),
-  assign others, or archive. Title/body edits need the create cap —
+  assign or release cards they do not hold, or archive. A holder may hand
+  its own card to another eligible profile (`tasks handoff`). Title/body edits need the create cap —
   claim-only keys can drive a card but cannot rewrite its text.
 - Boards need a whole-collection grant: folder-only or tag-only keys 403
   on every task route (the full-collection server message says so verbatim
@@ -153,8 +172,11 @@ abstains honestly instead of answering halfway.
   capability (notes are opt-in), or folder-/tag-only key on a board route.
   404: bad id (the server hides grant gaps as 404 too).
 - 409 on claim: someone already holds the card — the message names them.
+- Handoff 403: you do not hold the card (claim it, or ask an orchestrator)
+  or you tried to release it to nobody. 422: the target lacks a
+  whole-collection grant on this board, or the card is done/archived.
 - 422 SECRET_BLOCKED: the secret filter fired — it covers task
-  title/body/blockedReason/artifact text as well as notes. Strip keys,
-  tokens, and credentials and retry.
+  title/body/blockedReason/reviewNote/escalationReason/artifact text as
+  well as notes. Strip keys, tokens, and credentials and retry.
 - 429: minute throttle (slow down) or daily budget spent (resets tomorrow).
 - Cannot-reach errors: check the network and service status; `takibi version` probes it.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "takibibase",
-  "version": "1.8.0",
+  "version": "1.11.0",
   "description": "Thin CLI for the Takibi API: ask, search, tasks, docs, notes. Single file, zero dependencies.",
   "type": "module",
   "bin": {
@@ -15,7 +15,7 @@
     "node": ">=22"
   },
   "scripts": {
-    "test": "node --test notes.test.mjs skill.test.mjs upload.test.mjs"
+    "test": "node --test notes.test.mjs skill.test.mjs tasks.test.mjs upload.test.mjs"
   },
   "license": "SEE LICENSE IN LICENSE",
   "repository": {

package/takibi.mjs

@@ -37,7 +37,7 @@ import { homedir } from 'node:os';
 import { basename, join } from 'node:path';
 
 /** Baked fallback; the published package re-reads package.json next door. */
-const BAKED_VERSION = '1.8.0';
+const BAKED_VERSION = '1.11.0';
 const CLI_INFO = (() => {
   try {
     const pkg = JSON.parse(readFileSync(new URL('./package.json', import.meta.url), 'utf8'));
@@ -362,7 +362,10 @@ Commands:
   tasks list              Board cards for the project
   tasks get <id>          One card with body + artifacts
   tasks claim <id>        Claim an open to-do card (atomic, one winner)
-  tasks status <id> <st>  Move a card: todo | in_progress | review | done
+  tasks status <id> <st>  Move a card: todo | in_progress | review | done [--note <text>]
+  tasks handoff <id> <profile>  Hand a card you hold to another profile [--review --note <text>]
+  tasks escalate <id>       Ask the Founder for help on a held card [--reason <text>]
+  tasks deescalate <id>     Clear your escalation ("never mind")
   tasks artifact add <taskId> <url>   Attach a link-only artifact
   doc list                Documents (metadata)
   doc get <id>            One document's metadata
@@ -394,6 +397,10 @@ Global options (accepted before or after the command):
 Per-command options:
   ask/search: -q, --query <text> (or a bare positional), -k <n> (ask 1-12, search 1-20)
   tasks list: --all (include archived)
+  tasks status: --note <text> (review handoff note; cleared when the card leaves review)
+  tasks handoff: <profile> is a name or UUID on this board; --review moves the card to
+                 review in the same call, --note <text> leaves the review note with it
+  tasks escalate: --reason <text> (required, max 500 chars — what do you need from the Founder?)
   tasks artifact add: --note <text> --size <bytes> --hash <hex>
   doc list: --limit <n> (1-100)   doc text: --max-chars <n>
   doc upload: <file> (pdf, md, txt, docx, max 10MB)
@@ -417,7 +424,7 @@ to probe the API and \`takibi projects\` to see this key's scope
 Agents: \`takibi skill --install\` puts the takibi-use skill where
 assistants look for it.
 
-Reads are free. Export stamps included notes. Task claim/status/artifact writes and doc uploads
+Reads are free. Export stamps included notes. Task claim/status/handoff/artifact/escalation writes and doc uploads
 need owner approval in conversation (uploads also need the Uploads grant on the key).
 Account-only routes (delete, retry, download originals, PATCH docs/projects)
 are never the agent's to call — ask the account owner.
@@ -457,9 +464,9 @@ function parseArgv(argv) {
       i = ni;
     }
     else if (a.startsWith('--folder=')) globals.folder = a.slice('--folder='.length);
-    else if (a === '--query' || a === '-q' || a === '--q' || a === '-k' || a === '--limit' || a === '--max-chars' || a === '--all' || a === '--add' || a === '--note' || a === '--size' || a === '--hash' || a === '--problem' || a === '--tried' || a === '--worked' || a === '--failed' || a === '--next-time' || a === '--source' || a === '--since' || a === '--run-id' || a === '--install' || a === '--force' || a === '--agents' || a === '--claude' || a === '--codex' || a === '--dir') {
+    else if (a === '--query' || a === '-q' || a === '--q' || a === '-k' || a === '--limit' || a === '--max-chars' || a === '--all' || a === '--review' || a === '--add' || a === '--note' || a === '--reason' || a === '--size' || a === '--hash' || a === '--problem' || a === '--tried' || a === '--worked' || a === '--failed' || a === '--next-time' || a === '--source' || a === '--since' || a === '--run-id' || a === '--install' || a === '--force' || a === '--agents' || a === '--claude' || a === '--codex' || a === '--dir') {
       rest.push(a);
-      if (a !== '--all' && a !== '--install' && a !== '--force' && a !== '--agents' && a !== '--claude' && a !== '--codex') {
+      if (a !== '--all' && a !== '--review' && a !== '--install' && a !== '--force' && a !== '--agents' && a !== '--claude' && a !== '--codex') {
         const [v, ni] = takeValue(a, i);
         rest.push(v);
         i = ni;
@@ -533,6 +540,7 @@ function renderSearch(results, q) {
 
 const taskLine = (t) => {
   const bits = [t.id, `· ${t.status}`, `· ${t.title}`, `· ${t.assigneeName ?? 'unassigned'}`];
+  if (t.escalationReason) bits.push(`· escalated: ${t.escalationReason}`);
   if (t.blocked) bits.push(`· blocked: ${t.blockedReason || 'no reason given'}`);
   if (t.artifacts?.length) bits.push(`· ${t.artifacts.length} artifact${t.artifacts.length === 1 ? '' : 's'}`);
   if (t.archivedAt) bits.push('· archived');
@@ -542,6 +550,7 @@ const taskLine = (t) => {
 
 function renderTask(t) {
   out(taskLine(t));
+  if (t.reviewNote) out(`review: ${t.reviewNote}`);
   if (t.body) out(`\n${t.body}`);
   if (t.artifacts?.length) {
     out('');
@@ -634,6 +643,32 @@ async function listTasks(ctx, includeArchived) {
   return data.tasks ?? [];
 }
 
+/**
+ * Handoff target → {id}. UUIDs pass straight through (the server checks
+ * eligibility); names resolve exactly against GET /v1/tasks/assignees for
+ * this board — same exact-match-or-error rule as --project names.
+ */
+async function resolveAssignee(value, ctx) {
+  const v = String(value).trim();
+  if (UUID_RE.test(v)) return { id: v };
+  const data = await api('GET', '/v1/tasks/assignees', {
+    ...ctx,
+    query: qparams([['projectId', ctx.projectId]]),
+    label: 'tasks handoff',
+  });
+  const eligible = data?.assignees ?? [];
+  const matches = eligible.filter((a) => a.name === v);
+  if (matches.length > 1) {
+    throw new CliError(`More than one profile on this board is named ${JSON.stringify(v)}.`, {
+      hint: `Pass the profile UUID instead: ${matches.map((a) => a.id).join(', ')}.`,
+    });
+  }
+  if (matches[0]) return matches[0];
+  throw new CliError(`No profile named ${JSON.stringify(v)} can take cards on this board.`, {
+    hint: eligible.length > 0 ? `Eligible: ${eligible.map((a) => a.name).join(', ')}.` : 'No profile holds this whole board yet — ask the account owner.',
+  });
+}
+
 async function cmdTasks(tokens, globals) {
   if (globals.folder) throw usageError('--folder does not apply to tasks: cards are project-wide, folder grants stay a KB-read concept.');
   const [sub, ...rest] = tokens;
@@ -678,20 +713,58 @@ async function cmdTasks(tokens, globals) {
     return;
   }
   if (sub === 'status') {
-    const [id, to, extra] = rest;
-    if (!id || !to || extra) throw usageError('Usage: takibi tasks status <id> <todo|in_progress|review|done>');
+    const [id, to, ...flagTokens] = rest;
+    if (!id || !to) throw usageError('Usage: takibi tasks status <id> <todo|in_progress|review|done> [--note <text>]');
     if (!TASK_STATUSES.includes(to)) throw usageError(`Status is one of ${TASK_STATUSES.join(' | ')}, not ${JSON.stringify(to)}.`);
+    let note;
+    for (let i = 0; i < flagTokens.length; i++) {
+      const f = flagTokens[i];
+      if (f === '--note') note = flagTokens[++i];
+      else throw usageError(`Unexpected ${JSON.stringify(f)}. Usage: takibi tasks status <id> <todo|in_progress|review|done> [--note <text>]`);
+    }
+    if (note !== undefined && note === '') throw usageError('--note needs non-empty text.');
     const ctx = await ctxFor(globals, { needKey: true });
     const data = await api('PATCH', `/v1/tasks/${id}`, {
       ...ctx,
       query: qparams([['projectId', ctx.projectId]]),
-      body: { status: to },
+      body: { status: to, reviewNote: note },
       label: 'tasks status',
     });
     if (ctx.json) out(JSON.stringify(data, null, 2));
     else renderTask(data.task);
     return;
   }
+  if (sub === 'handoff') {
+    const usage = 'Usage: takibi tasks handoff <id> <profile-name-or-uuid> [--review] [--note <text>]';
+    const [id, target, ...flagTokens] = rest;
+    if (!id || !target || target.startsWith('--')) throw usageError(usage);
+    let review = false;
+    let note;
+    for (let i = 0; i < flagTokens.length; i++) {
+      const f = flagTokens[i];
+      if (f === '--review') review = true;
+      else if (f === '--note') note = flagTokens[++i];
+      else throw usageError(`Unexpected ${JSON.stringify(f)}. ${usage}`);
+    }
+    if (note !== undefined && note === '') throw usageError('--note needs non-empty text.');
+    // After the handoff this key no longer holds the card, so the note can
+    // only ride the same call — and only onto a card moving to review.
+    if (note !== undefined && !review) throw usageError('--note rides with --review: the handoff and the review note go in one call.');
+    const ctx = await ctxFor(globals, { needKey: true });
+    const assignee = await resolveAssignee(target, ctx);
+    const body = { assigneeProfileId: assignee.id };
+    if (review) body.status = 'review';
+    if (note !== undefined) body.reviewNote = note;
+    const data = await api('PATCH', `/v1/tasks/${id}`, {
+      ...ctx,
+      query: qparams([['projectId', ctx.projectId]]),
+      body,
+      label: 'tasks handoff',
+    });
+    if (ctx.json) out(JSON.stringify(data, null, 2));
+    else renderTask(data.task);
+    return;
+  }
   if (sub === 'artifact' || sub === 'artifacts') {
     const [verb, taskId, url, ...flagTokens] = rest;
     if (verb !== 'add' || !taskId || !url) throw usageError('Usage: takibi tasks artifact add <taskId> <url> [--note <t> --size <n> --hash <h>]');
@@ -721,7 +794,41 @@ async function cmdTasks(tokens, globals) {
     }
     return;
   }
-  throw usageError(`Unknown tasks command ${JSON.stringify(sub)}. Use list | get | claim | status | artifact add.`);
+  if (sub === 'escalate') {
+    const [id, ...flagTokens] = rest;
+    if (!id) throw usageError('Usage: takibi tasks escalate <id> --reason <text>');
+    let reason;
+    for (let i = 0; i < flagTokens.length; i++) {
+      const f = flagTokens[i];
+      if (f === '--reason') reason = flagTokens[++i];
+      else throw usageError(`Unexpected ${JSON.stringify(f)}. Usage: takibi tasks escalate <id> --reason <text>`);
+    }
+    if (reason === undefined || reason === '') throw usageError('--reason needs non-empty text: what do you need from the Founder?');
+    const ctx = await ctxFor(globals, { needKey: true });
+    const data = await api('POST', `/v1/tasks/${id}/escalate`, {
+      ...ctx,
+      query: qparams([['projectId', ctx.projectId]]),
+      body: { reason },
+      label: 'tasks escalate',
+    });
+    if (ctx.json) out(JSON.stringify(data, null, 2));
+    else renderTask(data.task);
+    return;
+  }
+  if (sub === 'deescalate') {
+    const [id, extra] = rest;
+    if (!id || extra) throw usageError('Usage: takibi tasks deescalate <id>');
+    const ctx = await ctxFor(globals, { needKey: true });
+    const data = await api('DELETE', `/v1/tasks/${id}/escalation`, {
+      ...ctx,
+      query: qparams([['projectId', ctx.projectId]]),
+      label: 'tasks deescalate',
+    });
+    if (ctx.json) out(JSON.stringify(data, null, 2));
+    else renderTask(data.task);
+    return;
+  }
+  throw usageError(`Unknown tasks command ${JSON.stringify(sub)}. Use list | get | claim | status | handoff | escalate | deescalate | artifact add.`);
 }
 
 async function cmdDoc(tokens, globals) {