@lumoai/cli 1.20.2 → 1.22.0

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 详情", "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 lineage", "lineage", "causal trail", "审计", "因果链", "成本归因", "trace context", "--signal", "usage signal health", "auto usage audit", "自动使用审计", "signal-health".'
+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 详情", "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", "task lineage", "lineage", "causal trail", "审计", "因果链", "成本归因", "trace context", "--signal", "usage signal health", "auto usage audit", "自动使用审计", "signal-health".'
 ---
 
 ## Prerequisites
@@ -25,6 +25,7 @@ The command catalog below is a **map**: it lists every command grouped by domain
 | `task context`, retrieval (`slack/web/figma context`, `comments list`, `pr show`) | [references/task-context.md](references/task-context.md)       |
 | `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)               |
 | `project list`, `milestone*`                                                      | [references/milestones.md](references/milestones.md)           |
 | `doc*`                                                                            | [references/docs.md](references/docs.md)                       |
 | `sprint*`                                                                         | [references/sprints.md](references/sprints.md)                 |
@@ -60,6 +61,11 @@ The command catalog below is a **map**: it lists every command grouped by domain
 - `lumo task show <id>` — print one task's detail
 - `lumo task comment <id> <body>` — leave a comment
 
+**Acceptance criteria（验收合约）** — see [criteria.md](references/criteria.md)
+
+- `lumo task criteria set <task> --file <criteria.json> [--human]` — submit the whole contract: default = initial agent draft (AGENT_DRAFT, locked once submitted); `--human` = a HUMAN_EDIT revision transcribed from the conversation (desired final list; items with `id` keep/update, missing ones are deleted)
+- `lumo task criteria list <task>` — print the contract (id, MACHINE/HUMAN, provenance source@round, checkpointer)
+
 **Artifacts & Figma** — see [artifacts-figma.md](references/artifacts-figma.md)
 
 - `lumo task artifact add/update/list/show/rm` — record spec/plan products on a task
@@ -114,6 +120,7 @@ Typical flow when a user says "help me with LUM-42":
 1. `lumo session attach LUM-42` — bind this session
 2. `lumo task context LUM-42` — load background
 3. Review unresolved items, PR-review todos, and the task description
-4. Begin working on the task
+4. **If the task has no acceptance criteria** (context shows the 草拟提醒 instead of a contract): draft 3–7 outcome-level criteria and submit them with `lumo task criteria set` **before writing the first line of code** — see [criteria.md](references/criteria.md) for the drafting guide
+5. Begin working on the task
 
 **Git-suggest at start:** when the session is unbound, session-start may infer the task from the git branch / recent commits and print a suggestion — `检测到 LUM-N … 运行 lumo session attach LUM-N 绑定。` — **without** binding. Confirm it's the right task, then run `lumo session attach <LUM-N>` yourself (binding only happens on an explicit attach). See [sessions.md](references/sessions.md) for the full session-start behavior.

package/assets/skill/references/criteria.md

@@ -0,0 +1,124 @@
+# Acceptance criteria（验收合约）
+
+The acceptance contract is a small set of structured criteria the task's work
+will be verified against (Acceptance v1, LUM-341/342). The agent drafts it;
+the server validates and stores it; verification rounds (`lumo verify`,
+Slice 1 任务 ③) judge against it. Criteria are injected at session start and
+in `lumo task context` as the `## 验收标准（合约）` section.
+
+## When to draft — the golden rule
+
+**Attach → read context → draft criteria → THEN write the first line of code.**
+
+If `lumo task context` / session-start shows 该任务尚无验收标准 instead of a
+contract, you MUST draft and submit criteria before starting implementation:
+
+1. Read the task description, comments, linked resources, and memory first —
+   the contract distills what "done" means, so understand the task before
+   writing it.
+2. Draft **3–7 criteria** (soft range — the server warns outside it but never
+   rejects; if you genuinely need more, merge related checks instead).
+3. Submit with `lumo task criteria set <task> --file <criteria.json>`.
+   Submission **locks the contract for agent edits** — get it right before
+   submitting, because afterwards only human revisions (`--human`) can change it.
+
+Once you (the agent) have started work, you can NOT change your own contract.
+That's by design: the contract is what your work gets judged against, not a
+to-do list you trim to fit what you built.
+
+## How to write good criteria
+
+- **Outcome-level definition of done, not micro-steps.** A criterion states a
+  verifiable result ("`lumo task criteria set` rejects a second agent draft
+  with 409"), not a task step ("add a check in the service").
+- **Repo-wide baselines don't take slots.** Tests pass / `tsc --noEmit` clean /
+  i18n locale parity / lint are already required by the repo's PR checklist —
+  never spend one of your 3–7 criteria on them.
+- **MACHINE vs HUMAN:**
+  - `MACHINE` = an executable check exists. It **must** carry a `checkpointer`
+    (the runnable check: a test command, script, probe…). The checkpointer
+    runs on the agent's machine; the structured verdict is reported back to
+    the server (执行在客户端，裁判在服务端).
+  - `HUMAN` = needs human judgment (UX feel, copy tone, design fidelity).
+  - **If you can't attach a checkpointer to a MACHINE criterion, demote it to
+    HUMAN** — the server rejects checkpointer-less MACHINE criteria rather
+    than silently rewriting them. Don't invent a fake checkpointer to keep it
+    MACHINE.
+- `evidenceRequired: true` marks criteria whose verdict must point at proof
+  (a MACHINE PASS always requires evidence regardless of this flag).
+
+## JSON file format
+
+`criteria.json` is a JSON array; one object per criterion:
+
+```json
+[
+  {
+    "statement": "PUT /api/tasks/[id]/criteria rejects a second AGENT_DRAFT submission with 409",
+    "verifierType": "MACHINE",
+    "checkpointer": "npx jest __tests__/task-criteria.service.test.ts -t 'agent lock'"
+  },
+  {
+    "statement": "The criteria section reads naturally as part of the task statement",
+    "verifierType": "HUMAN"
+  },
+  {
+    "statement": "Session-start injection shows the contract ahead of memory",
+    "verifierType": "MACHINE",
+    "checkpointer": "npx jest __tests__/cli/hook-runner-session-start-stdout.test.ts",
+    "evidenceRequired": true
+  }
+]
+```
+
+Fields: `statement` (required, ≤2000 chars), `verifierType` (`"MACHINE"` |
+`"HUMAN"`), `checkpointer` (required for MACHINE), `evidenceRequired`
+(optional, default false), `id` (only in `--human` revisions — see below).
+
+## Commands
+
+### `lumo task criteria set <task> --file <criteria.json>`
+
+Initial agent draft. Creates the whole contract as `AGENT_DRAFT` at round 0.
+Rejected with 409 once **any** criteria exist on the task — the agent lock.
+Echoes the stored criteria (with ids) plus the 3–7 soft-cap warning if
+outside range.
+
+### `lumo task criteria set <task> --file <criteria.json> --human`
+
+Record a **human contract revision** (HUMAN_EDIT), e.g. when the user changes
+the contract in conversation — you transcribe their decision. Allowed at any
+time, even after the agent lock. The file is the **desired final list**:
+
+- items carrying an `id` (from `criteria list`) keep that criterion — changed
+  fields update it and stamp it `HUMAN_EDIT`; identical fields leave it (and
+  its provenance) untouched
+- items without `id` are created as `HUMAN_EDIT`
+- existing criteria missing from the file are **deleted** — refused with 409
+  if the criterion already has verification runs (reword it instead)
+
+The revision is auto-recorded as a task comment with the session 出处
+(`X-Lumo-Session-Id`). **Transcribing the contract is allowed; transcribing a
+verdict is never** — human verdicts only enter through human-initiated paths
+(web UI / Slack action), and the agent has no write path to them.
+
+Only use `--human` for decisions a human actually made (in conversation, in a
+comment, in review). Never use it to work around your own lock.
+
+### `lumo task criteria list <task>`
+
+Print the contract: `<id>  [MACHINE|HUMAN]  SOURCE@rN  [evidence]  statement`
+plus an indented `↳ check:` line for checkpointers. Use it to fetch ids
+before a `--human` revision. Empty contract prints a drafting pointer.
+
+## Injection behavior
+
+- **Session start** (bound task): the contract is the highest-priority
+  section in the injection budget — ahead of memory/PR/Slack/Figma/web. If a
+  still-open task has no criteria, a 草拟提醒 is injected instead.
+- **`lumo session attach`**: prints the contract (or the 草拟提醒) right after
+  binding.
+- **`lumo task context`**: the `## 验收标准（合约）` section appears after the
+  task description, before memory.
+- Review-time gap findings (`REVIEW_ADDED`, appended at the round they
+  surface) arrive via the verification loop (任务 ③), not via `criteria set`.

package/assets/skill/references/sessions.md

@@ -49,6 +49,8 @@ What it does:
 - Calls `POST /api/sessions/<session_id>/bind-task` on the Lumo server, which sets the Session row's `taskId` and re-tags previously-untagged HookEvent rows in this session.
 - The binding lives entirely on the server (`Session.taskId`); subsequent hooks read it back via the session row. The CLI keeps no local sentinel.
 
+- Prints the task's **验收标准（合约）** (acceptance contract, LUM-342) right after the bind confirmation — or, when a still-open task has none, the 草拟提醒 telling you to draft 3–7 criteria before the first line of code (see [criteria.md](criteria.md)). The same section is auto-injected at session start when the session is already bound (highest priority in the injection budget, ahead of memory).
+
 **After attaching, always run `lumo task context <identifier>` to load the task background.**
 
 #### Overwriting an existing binding (LUM-266)

package/assets/skill/references/task-context.md

@@ -15,14 +15,15 @@ Example: `lumo task context LUM-42`
 The command prints a markdown document to stdout containing:
 
 1. **Task header** — identifier, title, status, description
-2. **Memory section** — cross-session learnings accumulated over prior sessions; treat as trusted background context
-3. **Inline source cards** — Slack / web / Figma / artifacts / documents / comments / Pull Requests (see "Context Retrieval" below)
-4. **PR Review 待办** — mirrored PR review comments as a checkbox todo list: each line-level reviewer comment (shown as `` `file:line` `` + the reviewer's ask + a link to the GitHub comment) and each `changes_requested` review summary (shown as "🛑 整体要求改动"). Present only when the task's PR(s) have review comments. This same block is **auto-injected at session start** (alongside the memory section) when the session is bound to a task — so reviewer asks surface without re-running `task context`.
-   - The **inline source cards** (Slack / web / Figma / PR) are likewise **auto-injected at session start** when the session is bound, under a single global token budget shared with the memory section (priority: memory > PR > Slack > Figma > web). Cards that don't fit the budget are degraded to a one-line manifest carrying just the title and its `lumo task … show` retrieval command — so you still know they exist and can pull the full content on demand.
-5. **Previous sessions** — ordered newest-first, each with:
+2. **验收标准（合约）** — the task's acceptance criteria (LUM-342), shown right after the header. Each line: `[MACHINE|HUMAN] statement` with a `↳ check:` line for MACHINE checkpointers; HUMAN_EDIT / REVIEW_ADDED provenance is tagged inline. If a still-open task has none, a 草拟提醒 appears instead — draft 3–7 criteria **before writing code** (see [criteria.md](criteria.md))
+3. **Memory section** — cross-session learnings accumulated over prior sessions; treat as trusted background context
+4. **Inline source cards** — Slack / web / Figma / artifacts / documents / comments / Pull Requests (see "Context Retrieval" below)
+5. **PR Review 待办** — mirrored PR review comments as a checkbox todo list: each line-level reviewer comment (shown as `` `file:line` `` + the reviewer's ask + a link to the GitHub comment) and each `changes_requested` review summary (shown as "🛑 整体要求改动"). Present only when the task's PR(s) have review comments. This same block is **auto-injected at session start** (alongside the memory section) when the session is bound to a task — so reviewer asks surface without re-running `task context`.
+   - The **inline source cards** (Slack / web / Figma / PR) are likewise **auto-injected at session start** when the session is bound, under a single global token budget shared with the memory section (priority: criteria > memory > PR > Slack > Figma > web). Cards that don't fit the budget are degraded to a one-line manifest carrying just the title and its `lumo task … show` retrieval command — so you still know they exist and can pull the full content on demand.
+6. **Previous sessions** — ordered newest-first, each with:
    - A headline summary of what was done
    - Unresolved items (carry-over TODOs from that session)
-6. **飞轮信号 · 历史 merge 贡献** — appended at the very end. For each context fragment with enough history, a one-line historical merge-contribution signal (e.g. `出现在 5 个已闭合任务·4 merged (80%)`), computed from accumulated lineage edges. Denominator = distinct tasks where the fragment appeared with a resolved (non-UNKNOWN) outcome; only fragments with ≥3 such tasks are shown (cold-start gate), so the block is often absent early on. This is **historical correlation, not causation** — don't read it as a prediction.
+7. **飞轮信号 · 历史 merge 贡献** — appended at the very end. For each context fragment with enough history, a one-line historical merge-contribution signal (e.g. `出现在 5 个已闭合任务·4 merged (80%)`), computed from accumulated lineage edges. Denominator = distinct tasks where the fragment appeared with a resolved (non-UNKNOWN) outcome; only fragments with ≥3 such tasks are shown (cold-start gate), so the block is often absent early on. This is **historical correlation, not causation** — don't read it as a prediction.
 
 ### How to use the context
 

package/dist/cli/src/commands/session-attach.js

@@ -112,6 +112,11 @@ async function sessionAttach(identifier, options = {}) {
     }
     console.log(`Attached session ${sessionId} to ${body.taskIdentifier} "${(0, sanitize_1.sanitizeField)(body.taskTitle)}"`);
     console.log(`Re-tagged ${body.retaggedEventCount} previously-untagged event${body.retaggedEventCount === 1 ? '' : 's'} in this session.`);
+    // Contract first: it's what the upcoming work is judged against (LUM-342).
+    if (body.criteriaSection) {
+        console.log('');
+        console.log((0, sanitize_1.sanitizeField)(body.criteriaSection));
+    }
     if (body.memorySection !== '') {
         console.log('');
         console.log((0, sanitize_1.sanitizeField)(body.memorySection));

package/dist/cli/src/commands/task-context.js

@@ -70,6 +70,12 @@ function formatTaskContextMarkdown(data, now) {
         lines.push(`**Description**: ${(0, sanitize_1.sanitizeField)(body)}`);
     }
     lines.push('');
+    // The acceptance contract leads (LUM-342): it's what the work is judged
+    // against, so it reads as part of the task statement itself.
+    if (data.criteriaSection && data.criteriaSection.trim().length > 0) {
+        lines.push((0, sanitize_1.sanitizeField)(data.criteriaSection.trimEnd()));
+        lines.push('');
+    }
     // Frontload memory before sessions: it's cold context the agent should see
     // first. Server returns "" when empty, in which case we skip the section.
     if (data.memorySection && data.memorySection.trim().length > 0) {

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

@@ -0,0 +1,69 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.formatCriteriaRows = formatCriteriaRows;
+exports.taskCriteriaList = taskCriteriaList;
+const config_1 = require("../lib/config");
+const api_1 = require("../lib/api");
+const sanitize_1 = require("../lib/sanitize");
+/**
+ * Render criteria rows for stdout. One line per criterion —
+ * `<id>  [TYPE]  SOURCE@rN  statement` — plus an indented checkpointer line
+ * when present. Shared by `criteria list` and the `criteria set` echo so the
+ * agent always sees the ids it needs for a later `--human` revision.
+ */
+function formatCriteriaRows(criteria) {
+    const lines = [];
+    for (const c of criteria) {
+        const provenance = `${c.source}@r${c.addedAtRound}`;
+        const evidence = c.evidenceRequired ? '  [evidence]' : '';
+        lines.push(`${c.id}  [${c.verifierType}]  ${provenance}${evidence}  ${(0, sanitize_1.sanitizeField)(c.statement)}`);
+        if (c.checkpointer) {
+            lines.push(`  ↳ check: ${(0, sanitize_1.sanitizeField)(c.checkpointer)}`);
+        }
+    }
+    return lines.length > 0 ? lines.join('\n') + '\n' : '';
+}
+/** `lumo task criteria list <task>` — print a task's acceptance contract. */
+async function taskCriteriaList(identifier) {
+    if (!identifier) {
+        console.error('Error: missing <task>. Usage: lumo task criteria list <LUM-42>');
+        return 1;
+    }
+    const creds = (0, config_1.readCredentials)();
+    if (!creds) {
+        console.error('Error: not logged in. Run `lumo auth login` first.');
+        return 1;
+    }
+    const apiUrl = (0, api_1.resolveAuthedApiUrl)(creds.apiUrl);
+    const base = (0, api_1.trimTrailingSlash)(apiUrl);
+    let res;
+    try {
+        res = await fetch(`${base}/api/tasks/${encodeURIComponent(identifier)}/criteria`, { headers: { Authorization: `Bearer ${creds.token}` } });
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        console.error(`Error: could not reach Lumo API at ${apiUrl} (${msg})`);
+        return 1;
+    }
+    if (res.status === 401) {
+        console.error('Error: API key invalid or revoked. Run `lumo auth login`.');
+        return 1;
+    }
+    if (res.status === 404) {
+        console.error(`Error: task ${identifier} not found in workspace ${creds.workspaceSlug}`);
+        return 1;
+    }
+    if (!res.ok) {
+        console.error(`Error: criteria list failed (HTTP ${res.status})`);
+        return 1;
+    }
+    const data = (await res.json());
+    if (data.criteria.length === 0) {
+        process.stdout.write(`No acceptance criteria on ${identifier} — draft 3–7 and submit with lumo task criteria set ${identifier} --file <criteria.json>\n`);
+        return;
+    }
+    process.stdout.write(formatCriteriaRows(data.criteria));
+    if (data.warning) {
+        process.stdout.write(`⚠ ${(0, sanitize_1.sanitizeField)(data.warning)}\n`);
+    }
+}

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

@@ -0,0 +1,126 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.taskCriteriaSet = taskCriteriaSet;
+const config_1 = require("../lib/config");
+const api_1 = require("../lib/api");
+const doc_input_1 = require("../lib/doc-input");
+const path_guard_1 = require("../lib/path-guard");
+const sanitize_1 = require("../lib/sanitize");
+const task_criteria_list_1 = require("./task-criteria-list");
+/** Client-side shape gate: fail fast on obviously malformed JSON before the
+ * round-trip. Full validation (statement length, MACHINE→checkpointer …)
+ * stays server-side. */
+function parseCriteriaJson(raw) {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return { ok: false, error: 'file is not valid JSON' };
+    }
+    if (!Array.isArray(parsed) || parsed.length === 0) {
+        return {
+            ok: false,
+            error: 'expected a non-empty JSON array of criteria, e.g. [{"statement":"…","verifierType":"MACHINE","checkpointer":"npx jest …"}]',
+        };
+    }
+    return { ok: true, items: parsed };
+}
+/**
+ * `lumo task criteria set <task> --file <criteria.json> [--human]`
+ *
+ * Submit a task's whole acceptance contract. Default = the agent's initial
+ * draft (AGENT_DRAFT, locked once submitted — the server rejects a second
+ * agent draft). `--human` records a HUMAN_EDIT revision: the file is the
+ * desired final list, items carrying an `id` keep/update that criterion,
+ * items without `id` are new, and existing criteria missing from the file
+ * are deleted (refused for criteria with recorded verification runs).
+ */
+async function taskCriteriaSet(identifier, options) {
+    if (!identifier) {
+        console.error('Error: missing <task>. Usage: lumo task criteria set <LUM-42> --file criteria.json');
+        return 1;
+    }
+    if (!options.file) {
+        console.error('Error: --file <path> is required (a JSON array of criteria).');
+        return 1;
+    }
+    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}`);
+        }
+        else {
+            console.error(`Error: refusing to read ${options.file} — ${verdict.detail}. ` +
+                `criteria --file must be a non-sensitive path inside the project directory.`);
+        }
+        return 1;
+    }
+    let raw;
+    try {
+        raw = await (0, doc_input_1.readFileUtf8)(verdict.resolved);
+    }
+    catch {
+        console.error(`Error: could not read file ${options.file}`);
+        return 1;
+    }
+    const parsed = parseCriteriaJson(raw);
+    if (!parsed.ok) {
+        console.error(`Error: ${parsed.error}`);
+        return 1;
+    }
+    const creds = (0, config_1.readCredentials)();
+    if (!creds) {
+        console.error('Error: not logged in. Run `lumo auth login` first.');
+        return 1;
+    }
+    const apiUrl = (0, api_1.resolveAuthedApiUrl)(creds.apiUrl);
+    const base = (0, api_1.trimTrailingSlash)(apiUrl);
+    const headers = {
+        Authorization: `Bearer ${creds.token}`,
+        'Content-Type': 'application/json',
+    };
+    // Session 出处 for HUMAN_EDIT transcriptions — the server records the
+    // revision (with this session id) as a task comment.
+    const sessionId = process.env.CLAUDE_CODE_SESSION_ID;
+    if (sessionId)
+        headers['X-Lumo-Session-Id'] = sessionId;
+    let res;
+    try {
+        res = await fetch(`${base}/api/tasks/${encodeURIComponent(identifier)}/criteria`, {
+            method: 'PUT',
+            headers,
+            body: JSON.stringify({
+                source: options.human ? 'HUMAN_EDIT' : 'AGENT_DRAFT',
+                criteria: parsed.items,
+            }),
+        });
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        console.error(`Error: could not reach Lumo API at ${apiUrl} (${msg})`);
+        return 1;
+    }
+    if (res.status === 401) {
+        console.error('Error: API key invalid or revoked. Run `lumo auth login`.');
+        return 1;
+    }
+    if (res.status === 404) {
+        console.error(`Error: task ${identifier} not found in workspace ${creds.workspaceSlug}`);
+        return 1;
+    }
+    if (!res.ok) {
+        const body = (await res.json().catch(() => null));
+        const detail = body && typeof body.error === 'string' ? (0, sanitize_1.sanitizeField)(body.error) : '';
+        console.error(`Error: criteria set failed (HTTP ${res.status})${detail ? ` — ${detail}` : ''}`);
+        return 1;
+    }
+    const data = (await res.json());
+    process.stdout.write(options.human
+        ? `Recorded HUMAN_EDIT contract revision on ${identifier} (${data.criteria.length} criteria)\n`
+        : `Acceptance contract drafted on ${identifier} (${data.criteria.length} criteria) — locked for agent edits; human revisions via --human\n`);
+    process.stdout.write((0, task_criteria_list_1.formatCriteriaRows)(data.criteria));
+    if (data.warning) {
+        process.stdout.write(`⚠ ${(0, sanitize_1.sanitizeField)(data.warning)}\n`);
+    }
+}

package/dist/cli/src/index.js

@@ -64,6 +64,8 @@ const memory_project_add_1 = require("./commands/memory-project-add");
 const memory_promote_1 = require("./commands/memory-promote");
 const memory_rm_1 = require("./commands/memory-rm");
 const task_artifact_add_1 = require("./commands/task-artifact-add");
+const task_criteria_set_1 = require("./commands/task-criteria-set");
+const task_criteria_list_1 = require("./commands/task-criteria-list");
 const task_artifact_list_1 = require("./commands/task-artifact-list");
 const task_artifact_show_1 = require("./commands/task-artifact-show");
 const task_artifact_rm_1 = require("./commands/task-artifact-rm");
@@ -343,6 +345,19 @@ taskMemory
     .option('--step <text>', 'procedural: a step (repeatable)', collect, [])
     .option('--agent <agent>', 'Producing agent: claude-code | codex | cursor | gemini-cli | github-copilot | windsurf (default claude-code)')
     .action(wrap((taskArg, opts) => (0, memory_task_add_1.memoryTaskAdd)(taskArg, opts)));
+const taskCriteria = task
+    .command('criteria')
+    .description('Acceptance criteria — the task\u2019s verification contract (LUM-342)');
+taskCriteria
+    .command('set <task>')
+    .description('Submit the whole acceptance contract from a JSON file. Default = initial agent draft (locked once submitted); --human records a HUMAN_EDIT revision (desired final list; items with "id" keep/update, missing ones are deleted).')
+    .requiredOption('--file <path>', 'JSON array of criteria: [{"statement","verifierType":"MACHINE"|"HUMAN","checkpointer?","evidenceRequired?","id?"}]')
+    .option('--human', 'Record a human contract revision (HUMAN_EDIT) transcribed from the conversation, with session 出处')
+    .action(wrap((taskId, options) => (0, task_criteria_set_1.taskCriteriaSet)(taskId, options)));
+taskCriteria
+    .command('list <task>')
+    .description('List a task\u2019s acceptance criteria (id, type, provenance, checkpointer)')
+    .action(wrap((taskId) => (0, task_criteria_list_1.taskCriteriaList)(taskId)));
 const taskArtifact = task
     .command('artifact')
     .description('Record spec-engineering artifacts (spec / plan / design …) on a task');

package/dist/cli/src/lib/hook-runner.js

@@ -114,6 +114,9 @@ function formatHookStdoutLines(path, responseBody, now = new Date()) {
     const card = renderRecoveryCard(body.previousSession, tb?.taskIdentifier ?? '', now);
     const envelope = sessionContextEnvelope([
         card,
+        // Acceptance contract right after the recovery card: it's what the
+        // session's work is judged against (LUM-342).
+        body.criteriaSection,
         body.memorySection,
         body.linkedResourcesSection,
         body.reviewTodosSection,
@@ -216,14 +219,17 @@ function resolveSessionStartStdout(responseBody, deps, now = new Date()) {
     return [formatSuggestLine(sessionId, match)];
 }
 /**
- * For stop/stop-failure hooks, read the transcript named in the payload and
- * fold cumulative token totals into the body under `_lumo_usage` so the server
- * can persist them on the Session. Best-effort: returns the body unchanged on
- * any failure (no transcript_path, unreadable, unparseable, no usage). The
- * hook is never blocked or failed by this.
+ * For stop/stop-failure/post-tool-batch hooks, read the transcript named in
+ * the payload and fold cumulative token totals into the body under
+ * `_lumo_usage` so the server can persist them on the Session. post-tool-batch
+ * carries usage so long single turns surface live burn before the first STOP
+ * (LUM-345); the server treats it as a flat-columns-only overwrite. Best-
+ * effort: returns the body unchanged on any failure (no transcript_path,
+ * unreadable, unparseable, no usage). The hook is never blocked or failed by
+ * this.
  */
 function augmentBodyWithUsage(path, body) {
-    if (path !== 'stop' && path !== 'stop-failure')
+    if (path !== 'stop' && path !== 'stop-failure' && path !== 'post-tool-batch')
         return body;
     let parsed;
     try {

package/dist/cli/src/lib/sanitize.js

@@ -1,17 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.sanitizeField = sanitizeField;
-// Matches C0 control chars EXCEPT tab (\x09) and newline (\x0a), DEL (\x7f),
-// and the C1 control range (\x80-\x9f). Includes ESC (\x1b) and the 8-bit CSI
-// introducer (\x9b) — both ANSI escape-sequence injection vectors. U+0080-U+009F
-// are never legitimate visible text, so stripping them is safe.
-const CONTROL_CHARS = /[\x00-\x08\x0b-\x1f\x7f-\x9f]/g;
-/**
- * Strip terminal control characters from untrusted, server-returned fields
- * before printing them, to prevent ANSI escape-sequence injection. Tab and
- * newline are preserved so fixed-width tables and multi-line bodies render
- * correctly. Callers handle optional values, e.g. `sanitizeField(name ?? '')`.
- */
-function sanitizeField(value) {
-    return value.replace(CONTROL_CHARS, '');
-}
+exports.sanitizeField = void 0;
+// Single source of truth lives in shared/src/sanitize.ts (LUM-346) — the
+// server applies the same character class at its untrusted render boundary.
+var sanitize_1 = require("../../../shared/src/sanitize");
+Object.defineProperty(exports, "sanitizeField", { enumerable: true, get: function () { return sanitize_1.sanitizeField; } });

package/dist/shared/src/index.js

@@ -1,7 +1,7 @@
 "use strict";
 // ── Agent Error types ────────────────────────────────────────────────────────
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.parseStreamJsonUsage = exports.tiptapToMarkdown = exports.markdownToTiptap = exports.AgentError = void 0;
+exports.sanitizeField = exports.parseStreamJsonUsage = exports.tiptapToMarkdown = exports.markdownToTiptap = exports.AgentError = void 0;
 exports.userFriendlyError = userFriendlyError;
 class AgentError extends Error {
     code;
@@ -36,3 +36,6 @@ Object.defineProperty(exports, "tiptapToMarkdown", { enumerable: true, get: func
 // ── Stream-json run usage parser ──────────────────────────────────────────────
 var stream_json_usage_1 = require("./stream-json-usage");
 Object.defineProperty(exports, "parseStreamJsonUsage", { enumerable: true, get: function () { return stream_json_usage_1.parseStreamJsonUsage; } });
+// ── Untrusted free-text sanitization ─────────────────────────────────────────
+var sanitize_1 = require("./sanitize");
+Object.defineProperty(exports, "sanitizeField", { enumerable: true, get: function () { return sanitize_1.sanitizeField; } });

package/dist/shared/src/sanitize.js

@@ -0,0 +1,22 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.sanitizeField = sanitizeField;
+// Matches C0 control chars EXCEPT tab (\x09) and newline (\x0a), DEL (\x7f),
+// and the C1 control range (\x80-\x9f). Includes ESC (\x1b) and the 8-bit CSI
+// introducer (\x9b) — both ANSI escape-sequence injection vectors. U+0080-U+009F
+// are never legitimate visible text, so stripping them is safe.
+const CONTROL_CHARS = /[\x00-\x08\x0b-\x1f\x7f-\x9f]/g;
+/**
+ * Strip terminal control characters from untrusted free text before it is
+ * printed (CLI) or injected into an agent's context (server render boundary),
+ * to prevent ANSI escape-sequence injection. Tab and newline are preserved so
+ * fixed-width tables and multi-line bodies render correctly. ids / urls /
+ * enums don't need this — only free text does. Callers handle optional
+ * values, e.g. `sanitizeField(name ?? '')`.
+ *
+ * Single source of truth shared by the CLI (cli/src/lib/sanitize.ts) and the
+ * server (lib/utils/sanitize.ts) so the two sides can never drift (LUM-346).
+ */
+function sanitizeField(value) {
+    return value.replace(CONTROL_CHARS, '');
+}

package/package.json

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