@lumoai/cli 1.25.0 → 1.25.1

package/assets/skill/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: lumo
-description: 'Use the Lumo CLI to load task context, manage session bindings, and run tasks / projects / milestones / sprints / docs / memory from the terminal. Activate when: the user mentions a Lumo task identifier (LUM-42 etc.), asks to load task background/context, wants to bind/check/detach a Claude Code session''s task, is about to start work on a task, or wants to create/update/list/show/comment on tasks, projects, milestones, sprints, documents, artifacts, Figma links, or memory. Triggers on: "LUM-", "task context", "load context", "session start", "session attach", "session status", "session detach", "which task", "what task am I on", "work on LUM", "session wrap", "wrap up session", "进度评论", "卡住检测", "fragment usage vote", "mark used fragments", "which fragments did I use", "--used", "上下文使用投票", "标记用过的记忆", "create task", "new task", "file a task", "list tasks", "my tasks", "show task", "view task", "comment on task", "update task", "change task status", "rename task", "reassign task", "mark task as done", "lumo next", "next task", "what should I work on", "推荐下一个任务", "list projects", "what projects", "milestone", "里程碑", "list/create/update/delete/show milestone", "set milestone", "attach/unbind milestone", "tasks in milestone", "search milestones", "find milestone", "milestone health", "at-risk", "overdue", "archive/unarchive milestone", "归档里程碑", "milestone summary", "里程碑复盘", "reorder/move milestone", "排序里程碑", "milestone add/remove", "挂任务到里程碑", "auth login", "log in", "logout", "sign out", "switch account", "whoami", "who am I", "current workspace", "登录", "切换账号", "create/update/list/show/delete doc", "write doc", "写文档", "新建文档", "修改文档", "查看文档", "bind/unbind doc", "把文档关联到任务", "doc scope", "personal/workspace doc", "tag", "add/remove tag", "标签", "share/unshare doc", "分享文档", "doc share-list", "viewer/editor/manager", "doc tree", "doc move", "move/reparent doc", "移动文档", "sprint", "冲刺", "迭代", "create/list/show/update/delete sprint", "start/close sprint", "开始/关闭冲刺", "add to sprint", "active sprints", "sprint summary", "冲刺总结", "把任务挂到冲刺", "sprint health", "sprint risk", "is this sprint at risk", "冲刺风险", "冲刺健康度", "sprint blockers", "冲刺阻塞", "lumo update", "upgrade lumo", "升级 lumo", "new lumo version", "lumo setup", "install lumo skill/hooks", "wire up lumo", "set up lumo", "安装 lumo", "配置 lumo", "task artifact", "artifact add/list/show/update/rm", "spec artifact", "record/attach spec", "attach plan", "记录 spec", "查看 artifact", figma, attach figma, figma link, 关联 figma, 设计稿, figma design, "memory", "记忆", "remember", "record a memory", "记一条", "promote memory", "promote to project", "沉淀", "task/project memory", "retrieval", "取全文", "拉全文", "task slack show", "看 thread", "show slack thread", "task web show", "web 正文", "task figma context", "figma metadata", "task comments list", "list comments", "看评论", "task pr show", "查看 PR", "show pr", "PR 详情", "task deps", "dependency", "dependencies", "依赖", "依赖边", "blocked by", "blocker", "confirm dependency", "dismiss dependency", "确认依赖", "忽略依赖", "import google doc", "sync google doc", "google drive", "doc import-gdoc", "doc sync", "导入/同步 google 文档", "mark blocked", "blocked tag", "标记 blocked", "stuck", "repeatedly failing", "worktree", "git worktree", "并行 worktree", "scaffold worktree", "新建 worktree", "node_modules 软链", "worktree 隔离", "lumo worktree add/rm/list", "task criteria", "criteria set", "criteria list", "acceptance criteria", "验收标准", "验收合约", "draft criteria", "草拟验收", "definition of done", "lumo verify", "verify task", "machine verification", "verification round", "机器验收", "自验", "验收轮", "claim done", "宣称完成", "--cause", "contract drift", "合约漂移", "task status", "acceptance status", "验收进度", "验收状态", "verification history", "验收历史", "next actions", "还差什么", "unmet criteria", "未满足", "resume task", "恢复任务", "被打回", "current round", "第几轮", "task lineage", "lineage", "causal trail", "审计", "因果链", "成本归因", "trace context", "--signal", "usage signal health", "auto usage audit", "自动使用审计", "signal-health".'
+description: 'Use the Lumo CLI to work with Lumo (project management for dev teams) from the terminal: load task context, bind/wrap Claude Code sessions, and create/update/list/show/comment on tasks, projects, milestones, sprints, documents, artifacts, Figma links, dependencies, and team memory — plus acceptance criteria, machine verification (verify / task status), lineage audit, worktree scaffolding, and CLI setup/auth/update. Activate when the user mentions a Lumo task identifier (LUM-N) or the lumo CLI; asks to load task background or bind/check/wrap a session; manages any of the resources above in Lumo; is starting, resuming, or about to claim completion of a task; or asks what to work on next. Key triggers: "LUM-", "lumo", "task context", "session attach", "session wrap", "验收", "verify", "task status", "milestone", "里程碑", "sprint", "冲刺", "文档", "记忆", "memory", "依赖", "deps", "lineage", "worktree", "下一个任务", "what should I work on", "设计稿", "验收标准", "机器验收", "恢复任务".'
 ---
 
 ## Prerequisites
@@ -26,7 +26,7 @@ The command catalog below is a **map**: it lists every command grouped by domain
 | `task create/update/list/show/comment`, `next`                                    | [references/tasks.md](references/tasks.md)                     |
 | `task artifact*`, `task figma*`                                                   | [references/artifacts-figma.md](references/artifacts-figma.md) |
 | `task criteria set/list`, drafting the acceptance contract                        | [references/criteria.md](references/criteria.md)               |
-| `verify`, `task status` — machine verification loop, claim-done flow, 自查/恢复    | [references/verify.md](references/verify.md)                   |
+| `verify`, `task status` — machine verification loop, claim-done flow, 自查/恢复   | [references/verify.md](references/verify.md)                   |
 | `project list`, `milestone*`                                                      | [references/milestones.md](references/milestones.md)           |
 | `doc*`                                                                            | [references/docs.md](references/docs.md)                       |
 | `sprint*`                                                                         | [references/sprints.md](references/sprints.md)                 |
@@ -128,6 +128,20 @@ The command catalog below is a **map**: it lists every command grouped by domain
 - `lumo worktree rm <LUM-N> --yes` — remove a worktree (keeps the branch unless `--delete-branch`)
 - `lumo worktree list` — list `.worktrees/` worktrees (task id, branch, dirty, node_modules link)
 
+## Commands & flags that do NOT exist (common mistakes)
+
+Measured from real agent sessions (LUM-392) — don't guess these:
+
+- No `lumo session start` — binding is `lumo session attach <LUM-N>`
+- No `lumo task delete` — tasks can't be deleted from the CLI (web UI only)
+- No `lumo task artifact edit` — it's `lumo task artifact update`
+- No `lumo auth status` — identity check is `lumo whoami`
+- No `--body` on `lumo task comment` — the body is a positional arg: `lumo task comment LUM-N "text"`
+- No `--content` on `task/project memory add` — memory is structured fields (`--category` + per-category flags), see [memory.md](references/memory.md)
+- No global `--verbose` flag on any command
+- `lumo task comments list` (plural) **reads** the thread; `lumo task comment` (singular) **writes** one
+- Status updates: `lumo task update LUM-N --status done` is one direct call — do **not** walk `in_progress → in_review → done` step by step (see [tasks.md](references/tasks.md) for the transition matrix; under the verify flow you shouldn't be setting `in_review`/`done` yourself at all)
+
 ## Core workflow
 
 Typical flow when a user says "help me with LUM-42":

package/assets/skill/references/tasks.md

@@ -95,6 +95,23 @@ Tags: urgent
 
 The `Tags:` line is omitted when the resulting tag set is empty.
 
+### Status transitions — direct moves are legal
+
+The server's transition matrix (`lib/task/state-machine.ts`):
+
+| From        | Allowed targets                                     |
+| ----------- | --------------------------------------------------- |
+| TODO        | IN_PROGRESS, IN_REVIEW, DONE                        |
+| IN_PROGRESS | TODO, IN_REVIEW, DONE                               |
+| IN_REVIEW   | TODO, IN_PROGRESS, DONE                             |
+| DONE        | TODO, IN_PROGRESS (reopen only — **not** IN_REVIEW) |
+
+Practical rules:
+
+- **One call suffices.** `--status done` straight from TODO or IN_PROGRESS is legal — never walk `in_progress → in_review → done` as a ritual (measured in LUM-392: 70 such chains wasted ~75 calls).
+- **Under the verify flow you don't set `in_review`/`done` at all** — `lumo verify` moves the task to IN_REVIEW on all-pass and the DONE adjudication is human-only.
+- **DONE → IN_REVIEW is rejected (409).** To attach follow-up context to a DONE task, use `lumo task comment` instead of reopening.
+
 ### When to suggest `task update`
 
 - The user describes a state change in natural language (e.g. "mark LUM-48 as in progress", "rename LUM-12 to ...", "assign LUM-30 to me", "bump the priority on LUM-7").
@@ -237,11 +254,13 @@ DISMISSED
 CONFIRMED and SUGGESTED rows show the other task's identifier, title, current status, and source/evidence. DISMISSED rows render as `[shortId] <direction> <identifier> · 已忽略` only — no title, status, or source.
 
 When there are no edges at all the output is:
+
 ```
 Dependencies for LUM-42: 无依赖边。
 ```
 
 **Evidence fields by detection signal:**
+
 - `shared_files` — `shared_files(N 个共享文件: path1, path2, …)` — number of shared write-touched files in the 14-day window, plus up to 5 sample paths.
 - `task_mention` — `task_mention(description)` or `task_mention(comment)` — the surface where the mention appeared.
 
@@ -258,6 +277,7 @@ lumo task deps add LUM-42 --blocked-by LUM-9
 Both `<LUM-N>` and `--blocked-by` are required. The command errors on usage if either is missing.
 
 **Service semantics (read before using):**
+
 - **Self-edge** → 400 ("A task cannot depend on itself").
 - **CONFIRMED edge in the same direction already exists** → 409 ("Dependency already exists").
 - **CONFIRMED edge in the reverse direction already exists** → the cycle guard fires and returns 409 ("Dependency would create a cycle").
@@ -275,11 +295,13 @@ lumo task deps confirm LUM-42 e5f6a7b8 --reverse  # flip direction before confir
 ```
 
 **Edge selector semantics** (shared by `confirm`, `dismiss`, `rm`):
+
 - **Other task's identifier** (e.g., `LUM-55`) — case-insensitive exact match against the edge's other-task identifier. Resolves unambiguously when there is exactly one edge to that task.
 - **Edge-id prefix** — at least 6 characters of the short id (e.g., `e5f6a7`). Must match exactly one edge.
 - If zero or more than one edge matches → prints all candidate edges with short ids and exits 1. Retry with a more specific selector.
 
 **`--reverse` semantics:**
+
 - The detector's direction heuristic is best-effort. If the suggested direction is backwards (e.g., the detector says "LUM-42 blocks LUM-55" but actually LUM-55 blocks LUM-42), confirm with `--reverse` to flip before writing.
 - The service checks that the reversed pair does not already have an edge (→ 409), and re-runs the cycle guard with the flipped direction.
 

package/dist/cli/src/commands/doc-list.js

@@ -9,6 +9,10 @@ const doc_create_1 = require("./doc-create");
 const doc_tree_1 = require("../lib/doc-tree");
 const sanitize_1 = require("../lib/sanitize");
 function visibilityLabel(v) {
+    // Some routes (e.g. /api/tasks/<id>/documents) have returned rows without a
+    // visibility field at runtime — fall back instead of crashing on .padEnd.
+    if (!v)
+        return '-';
     if (v === 'PRIVATE')
         return 'PERSONAL';
     return v;

package/dist/cli/src/commands/memory-promote.js

@@ -20,7 +20,10 @@ async function memoryPromote(memoryId) {
     try {
         res = await fetch(`${base}/api/memories/${encodeURIComponent(memoryId)}`, {
             method: 'PATCH',
-            headers: { Authorization: `Bearer ${creds.token}`, 'Content-Type': 'application/json' },
+            headers: {
+                Authorization: `Bearer ${creds.token}`,
+                'Content-Type': 'application/json',
+            },
             body: JSON.stringify({ scope: 'PROJECT' }),
         });
     }
@@ -29,7 +32,7 @@ async function memoryPromote(memoryId) {
         return 1;
     }
     if (res.status === 404) {
-        console.error(`Error: memory ${memoryId} not found`);
+        console.error(`Error: memory ${memoryId} not found — pass the full memory id (cuid) from \`lumo task memory list\` / \`lumo project memory list\`; truncated id prefixes are not resolved`);
         return 1;
     }
     if (res.status === 409) {
@@ -43,8 +46,12 @@ async function memoryPromote(memoryId) {
             if (typeof b.error === 'string')
                 m = b.error;
         }
-        catch { /* */ }
-        console.error(m ? `Error: ${(0, sanitize_1.sanitizeField)(m)}` : `Error: promote failed (HTTP ${res.status})`);
+        catch {
+            /* */
+        }
+        console.error(m
+            ? `Error: ${(0, sanitize_1.sanitizeField)(m)}`
+            : `Error: promote failed (HTTP ${res.status})`);
         return 1;
     }
     process.stdout.write(`Promoted ${memoryId} to PROJECT — every agent on this project now sees it.\n` +

package/dist/cli/src/commands/memory-rm.js

@@ -31,7 +31,7 @@ async function memoryRm(memoryId, options) {
         return 1;
     }
     if (res.status === 404) {
-        console.error(`Error: memory ${memoryId} not found`);
+        console.error(`Error: memory ${memoryId} not found — pass the full memory id (cuid) from \`lumo task memory list\` / \`lumo project memory list\`; truncated id prefixes are not resolved`);
         return 1;
     }
     if (res.status !== 204) {

package/dist/cli/src/commands/task-artifact-add.js

@@ -44,7 +44,7 @@ async function taskArtifactAdd(identifier, options) {
     const verdict = (0, path_guard_1.checkArtifactFilePath)(options.file);
     if (!verdict.ok) {
         if (verdict.reason === 'unreadable') {
-            console.error(`Error: could not read file ${options.file}`);
+            console.error(`Error: ${(0, doc_input_1.unreadableFileMessage)(options.file)}`);
         }
         else {
             console.error(`Error: refusing to read ${options.file} — ${verdict.detail}. ` +
@@ -57,7 +57,7 @@ async function taskArtifactAdd(identifier, options) {
         content = await (0, doc_input_1.readFileUtf8)(verdict.resolved);
     }
     catch {
-        console.error(`Error: could not read file ${options.file}`);
+        console.error(`Error: ${(0, doc_input_1.unreadableFileMessage)(options.file)}`);
         return 1;
     }
     if (content.trim().length === 0) {

package/dist/cli/src/commands/task-criteria-set.js

@@ -55,7 +55,7 @@ async function taskCriteriaSet(identifier, options) {
     const verdict = (0, path_guard_1.checkArtifactFilePath)(options.file);
     if (!verdict.ok) {
         if (verdict.reason === 'unreadable') {
-            console.error(`Error: could not read file ${options.file}`);
+            console.error(`Error: ${(0, doc_input_1.unreadableFileMessage)(options.file)}`);
         }
         else {
             console.error(`Error: refusing to read ${options.file} — ${verdict.detail}. ` +
@@ -68,7 +68,7 @@ async function taskCriteriaSet(identifier, options) {
         raw = await (0, doc_input_1.readFileUtf8)(verdict.resolved);
     }
     catch {
-        console.error(`Error: could not read file ${options.file}`);
+        console.error(`Error: ${(0, doc_input_1.unreadableFileMessage)(options.file)}`);
         return 1;
     }
     const parsed = parseCriteriaJson(raw);

package/dist/cli/src/index.js

@@ -172,7 +172,12 @@ function wrap(fn) {
 const program = new commander_1.Command()
     .name('lumo')
     .description('Lumo CLI — manage tasks and sessions from the terminal')
-    .version(pkg.version);
+    .version(pkg.version)
+    // Make usage errors actionable for agents: suggest near-miss spellings and
+    // point at --help instead of dead-ending on "unknown option". Subcommands
+    // created via .command() inherit these settings.
+    .showSuggestionAfterError(true)
+    .showHelpAfterError('(run the command with --help to list its valid flags and arguments)');
 const auth = program.command('auth').description('Manage Lumo authentication');
 auth
     .command('login')

package/dist/cli/src/lib/doc-input.js

@@ -33,6 +33,7 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.unreadableFileMessage = unreadableFileMessage;
 exports.resolveDocContent = resolveDocContent;
 exports.readStdinToString = readStdinToString;
 exports.readFileUtf8 = readFileUtf8;
@@ -45,6 +46,14 @@ const path_guard_1 = require("./path-guard");
  * mutually exclusive. stdin is only consulted when neither flag is set
  * and the shell is non-TTY.
  */
+/**
+ * Actionable message for an unreadable --file path: agents most often pass a
+ * path that doesn't exist relative to the current working directory.
+ */
+function unreadableFileMessage(file) {
+    return (`could not read file ${file} (cwd: ${process.cwd()}) — ` +
+        `check the path exists; pass a project-local relative path`);
+}
 async function resolveDocContent(args) {
     const hasContent = args.content !== undefined;
     const hasFile = args.file !== undefined && args.file.length > 0;
@@ -62,7 +71,7 @@ async function resolveDocContent(args) {
             return {
                 kind: 'error',
                 message: check.reason === 'unreadable'
-                    ? `could not read file ${args.file}`
+                    ? unreadableFileMessage(args.file)
                     : `refusing to read ${args.file} — ${check.detail}. ` +
                         `--file must be a non-sensitive path inside the project directory.`,
             };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lumoai/cli",
-  "version": "1.25.0",
+  "version": "1.25.1",
   "description": "Lumo CLI — manage tasks and sessions from the terminal",
   "license": "MIT",
   "author": "cli@uselumo.ai",