@lumoai/cli 1.30.0 → 1.31.0

package/assets/skill/SKILL.md

@@ -80,6 +80,7 @@ The command catalog below is a **map**: it lists every command grouped by domain
 
 - `lumo verify [task] [--timeout <seconds>]` — run every MACHINE criterion's checkpointer locally, report one structured PASS/FAIL verdict per criterion to the server, print next actions. Defaults to the session-bound task. Round cap 3: an all-pass round moves the task to IN_REVIEW (agent stops there); a round-3 fail escalates to a human (stop retrying). **Run this before claiming a task is done.**
 - `lumo task status [task] [--json]` — read-only acceptance self-check (no LLM, milliseconds): the contract with each criterion's latest verdict (REVIEW_ADDED provenance visible), verification history, current round, last round's failure reasons, and `nextActions` = the unmet criteria (the declarative "what's next" — no separate plan). Defaults to the session-bound task; `--json` emits a versioned payload (`version` field). **Run it first when resuming a task in a new session or after a verification round was rejected.**
+- `lumo verdict [task] --pass | --pass-with-followup | --fail` — acceptance verdicts (LUM-422). `--pass` / `--pass-with-followup` open the browser to the human verdict bar focused on the passing action (a deep link — **records nothing**; a passing data row is only ever a human's own click). `--fail --reason <enum> [--note <text>] [--criterion <id>…]` records an **AGENT send-back** (verifierType=AGENT, verdict hard-coded FAIL) and bounces the task to IN_PROGRESS. Defaults to the session-bound task. **An unresolved send-back (machine/AGENT/human FAIL) blocks the agent/CLI DONE transition with 409** — clear it (re-verify) before `task update --status done`.
 
 **Artifacts & Figma** — see [artifacts-figma.md](references/artifacts-figma.md)
 

package/assets/skill/references/artifacts-figma.md

@@ -96,6 +96,11 @@ cfl_xxx3  Onboarding       (file-level)         2026-05-20  ⚠ thumbnail stale
 
 Accepts a `cfl_*` cuid or the original URL. Idempotent (`Not linked: ...` + exit 0 when no match).
 
+```bash
+lumo task figma rm LUM-42 cfl_xxx1
+lumo task figma rm LUM-42 "https://www.figma.com/design/abc123/Onboarding?node-id=1-234"
+```
+
 #### `lumo task figma refresh <task>` — manual refresh
 
 Re-fetches metadata + thumbnail for every Figma link on the task. Per-link

package/assets/skill/references/criteria.md

@@ -67,6 +67,74 @@ must track the size of the work — it is not a fixed ritual:
 - `evidenceRequired: true` marks criteria whose verdict must point at proof
   (a MACHINE PASS always requires evidence regardless of this flag).
 
+### Invariant (negative-assertion) criteria
+
+Most criteria assert that **something that should happen, happened** ("the
+endpoint returns 409", "the section renders"). An _invariant criterion_ asserts
+the dual: that **something that must not happen, didn't** — the change left an
+explicit don't-touch surface intact. This is the acceptance analogue of
+AppWorld's _collateral-damage_ checks (arXiv 2407.18901) and ToolSandbox's
+_minefield_ states (arXiv 2408.04682): a finished task should be judged not only
+on the intended effect but on the forbidden effects it avoided. `lumo verify`
+already judges final state per round, so an invariant fits the existing
+machinery with no new mechanism — it's a drafting habit, not a feature.
+
+**When to write one.** Add a single invariant criterion when the task has a
+concrete, nameable surface the change must not disturb — a data-destruction red
+line, a structure guard, an always-green baseline set, a diff that must stay
+in-bounds, a standing budget. It is decision support, not a ritual: reach for it
+only when you can point at the surface. If the only invariant you can name is
+"don't break the build", that's already the repo's PR baseline (tests / `tsc` /
+lint / i18n parity) — don't spend a slot restating it.
+
+**How to phrase it.** State the invariant as _still holding after the change_,
+not as a step you took. The **c-CRAB boundary** is the hard rule: the check
+encodes **"the problem does not (re)occur"**, never **"a specific fix exists"**.
+Write "`prisma/migrations/` has no deleted files vs origin/main" (the bad state
+is absent) — not "the migration-delete guard function is present" (a named fix).
+The first survives a refactor of _how_ the invariant is enforced; the second
+re-fails the moment someone renames the guard, and passes even if the protection
+was gutted some other way.
+
+**Pairing with a checkpointer.** An invariant almost always has a runnable check
+— that's its advantage — so prefer MACHINE. The existing `checkpointer` syntax
+carries it as-is: a `git diff` path/filter probe, a full-suite `jest` run, a
+structure-verify script, a parity check. Two real-repo examples:
+
+- **`prisma/migrations/` files are never deleted** (the CLAUDE.md red line). The
+  bad state is a deleted migration file in the diff:
+
+  ```json
+  {
+    "statement": "No file under prisma/migrations/ is deleted by this change (vs origin/main)",
+    "verifierType": "MACHINE",
+    "checkpointer": "bash -c \"test -z \\\"$(git diff --diff-filter=D --name-only origin/main -- prisma/migrations/)\\\"\""
+  }
+  ```
+
+- **A live-doc's table structure is not flattened** (the LUM-349 incident: an
+  HTML→md round-trip silently collapsed tables to plain text). The verify script
+  hard-fails if any table / row / heading count shrank:
+
+  ```json
+  {
+    "statement": "Live-doc keeps its table structure after the edit (no rows/headings dropped)",
+    "verifierType": "MACHINE",
+    "checkpointer": "npx tsx scripts/verify-live-doc.ts <docId> docs/live-docs/<file>.md"
+  }
+  ```
+
+A third lives in a current contract you can copy: **LUM-415**'s "SKILL.md
+frontmatter description stays ≤ 1000 chars" — the standing context-budget
+invariant (the description is resident in every session), checkpointed by the
+`description cap` case in
+`scripts/analysis/lum392-cli-friction/__tests__/doc-examples.test.ts`.
+
+One invariant criterion is usually enough — it's the guardrail, not the whole
+contract. Pair it with the positive criteria that say what the change should
+achieve; together they assert _did the right thing_ **and** _touched nothing
+it shouldn't_.
+
 ## JSON file format
 
 `criteria.json` is a JSON array; one object per criterion:
@@ -104,6 +172,13 @@ 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.
 
+```bash
+lumo task criteria set LUM-42 --file criteria-lum42.json
+```
+
+(`--file` must point inside the current project directory — write the JSON to
+the repo root or a subdirectory, not `/tmp`, and delete it after submission.)
+
 ### `lumo task criteria set <task> --file <criteria.json> --human`
 
 Record a **human contract revision** (HUMAN_EDIT), e.g. when the user changes
@@ -125,6 +200,11 @@ verdict is never** — human verdicts only enter through human-initiated paths
 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.
 
+```bash
+lumo task criteria set LUM-42 --file criteria-revision.json --human
+lumo task criteria set LUM-42 --file criteria-revision.json --human --cause SCOPE_CHANGE
+```
+
 Optionally annotate **why** the contract drifted with
 `--cause <NEW_INFO|SCOPE_CHANGE|DRAFT_BLIND_SPOT|GRANULARITY|OTHER>` — pick
 the tag from the human's stated reason (new information, scope moved, the
@@ -139,6 +219,10 @@ 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.
 
+```bash
+lumo task criteria list LUM-42
+```
+
 ## Injection behavior
 
 - **Session start** (bound task): the contract is the highest-priority

package/assets/skill/references/docs.md

@@ -132,12 +132,12 @@ Use default mode when the user wants to read a doc; use `--raw` whenever the ful
 
 Replaces the **whole addressed section** (heading line included, subsections included) with the provided content, server-side, leaving every byte outside the section untouched. The new content comes from `--content`, `--file`, or piped stdin (one required; `--file` is sandboxed like `doc update`).
 
-| Flag                  | Type   | Notes                                                                                               |
-| --------------------- | ------ | --------------------------------------------------------------------------------------------------- |
-| `--section <heading>` | string | Required. Heading text addressing the section; prefix `#…` pins the depth.                          |
-| `--content <text>`    | string | New section content (include the heading line — the whole section is replaced verbatim).            |
-| `--file <path>`       | string | New section content from file (project-local sandbox).                                              |
-| `--if-revision <n>`   | int    | Only apply if the body is still at revision `n`. Recommended whenever the edit base was read earlier. |
+| Flag                  | Type    | Notes                                                                                                       |
+| --------------------- | ------- | ----------------------------------------------------------------------------------------------------------- |
+| `--section <heading>` | string  | Required. Heading text addressing the section; prefix `#…` pins the depth.                                  |
+| `--content <text>`    | string  | New section content (include the heading line — the whole section is replaced verbatim).                    |
+| `--file <path>`       | string  | New section content from file (project-local sandbox).                                                      |
+| `--if-revision <n>`   | int     | Only apply if the body is still at revision `n`. Recommended whenever the edit base was read earlier.       |
 | `--allow-shrink`      | boolean | Let the patch through even when it drops tables/rows/headings within the addressed section (422 otherwise). |
 
 Concurrency: the splice always commits **conditionally** on the revision the server read the source at — even without `--if-revision`, a concurrent body edit between read and write returns 409 instead of clobbering. On 409 the CLI prints the server reason plus a re-read-and-retry hint and exits 1.
@@ -164,11 +164,11 @@ lumo doc patch cmd_xxx --section "D 状态表" --file sec.md --if-revision 6
 
 Inserts the new content at the **end of the addressed section** (just before the next same-or-higher-level heading), or at the end of the document when `--section` is omitted. Pure insertion: no pre-existing byte is modified, which makes it the natural write for running logs, ledgers and queues. Content channels and sandbox are the same as `doc patch`; separator blank lines are added automatically.
 
-| Flag                  | Type   | Notes                                                                       |
-| --------------------- | ------ | --------------------------------------------------------------------------- |
-| `--section <heading>` | string | Optional. Omit to append at the document end.                               |
-| `--content <text>`    | string | Content to append.                                                          |
-| `--file <path>`       | string | Content from file (project-local sandbox).                                  |
+| Flag                  | Type   | Notes                                                                        |
+| --------------------- | ------ | ---------------------------------------------------------------------------- |
+| `--section <heading>` | string | Optional. Omit to append at the document end.                                |
+| `--content <text>`    | string | Content to append.                                                           |
+| `--file <path>`       | string | Content from file (project-local sandbox).                                   |
 | `--if-revision <n>`   | int    | Only apply if the body is still at revision `n`; 409 + retry hint otherwise. |
 
 Same concurrency contract as `doc patch` (always a conditional commit; 409 on conflict). Requires a stored markdown source.
@@ -188,8 +188,8 @@ echo "## 2026-06-10\n吸收了 3 篇" | lumo doc append cmd_xxx   # document end
 
 Compares the server-side stored markdown source (the byte-identical last markdown upload) against a local file, making remote/local split-brain visible on demand.
 
-| Flag            | Type   | Notes                                                                              |
-| --------------- | ------ | ---------------------------------------------------------------------------------- |
+| Flag            | Type   | Notes                                                                             |
+| --------------- | ------ | --------------------------------------------------------------------------------- |
 | `--file <path>` | string | Required. Local markdown file; same project-local sandbox as `doc update --file`. |
 
 Exit codes: **0** = byte-identical (prints `Clean: …`), **1** = divergent (prints a unified diff, `--- remote/<id> (sourceMarkdown)` vs `+++ local/<file>`) or error. A doc without a stored markdown source errors explicitly (upload a markdown base once, then diff works).
@@ -278,6 +278,10 @@ lumo doc delete cmd_xxx --yes
 
 Adds an explicit DocumentMention row. Survives content edits in the Web UI. If a CONTENT-derived mention already exists for the same pair, it's upgraded to EXPLICIT so a later `unbind` can remove it.
 
+```bash
+lumo doc bind cmd_xxx LUM-42
+```
+
 Output:
 
 ```

package/assets/skill/references/memory.md

@@ -19,7 +19,7 @@ lumo task memory add [LUM-N] --category trap --trigger "..." --outcome "..." [--
 lumo task memory add [LUM-N] --category decision --what "..." --why "..." [--alternatives "..."] [--implications "..."] [--agent <agent>]
 lumo task memory add [LUM-N] --category convention --rule "..." --applies "..." [--agent <agent>]
 lumo task memory add [LUM-N] --category procedural --workflow "..." --trigger "..." [--step "..." --step "..."] [--agent <agent>]
-lumo project memory add [<project>] --category ... [--agent <agent>]   # same flags; records at PROJECT scope
+lumo project memory add [<project>] --category convention --rule "..." --applies "..." [--agent <agent>]   # same per-category flags as task memory add; records at PROJECT scope
 
 # --agent values: claude-code | codex | cursor | gemini-cli | github-copilot | windsurf (default claude-code)
 # Aliases: gemini → gemini-cli, copilot → github-copilot (case-insensitive)
@@ -34,6 +34,23 @@ When the session is bound (`lumo session attach <LUM-N>`), omit the identifier:
 `lumo task memory add --category trap --trigger ... --outcome ...` records onto
 the bound task; `lumo project memory add ...` records onto its project.
 
+Real calls (memory fields are structured per category — there is **no**
+`--content` flag):
+
+```bash
+# Minimal — session bound, identifier omitted
+lumo task memory add --category trap --trigger "npx tsc --noEmit passes locally but CI fails on exactOptionalPropertyTypes" --outcome "PR goes red after merge"
+lumo project memory add --category convention --rule "CLI tag-modify commands print a final 'Tags:' line" --applies "lumo doc/task create and update"
+
+# Full form — explicit identifier, all optional fields
+lumo task memory add LUM-42 --category decision --what "Store doc content as Tiptap-serialized HTML" --why "markdown-to-JSON and markdown-to-HTML paths drifted" --alternatives "store Tiptap JSON" --implications "all markdown input goes through markdownToHtml" --agent claude-code
+lumo project memory add lumo --category procedural --workflow "Regenerate the CLI grammar snapshot" --trigger "any cli/src/commands change" --step "npx tsx scripts/analysis/lum392-cli-friction/emit-grammar.ts" --step "npx jest scripts/analysis/lum392-cli-friction" --agent claude-code
+
+# Curate
+lumo memory promote cmpi19iqabc123
+lumo memory rm cmpi19iqabc123 --yes
+```
+
 ### Reconcile-on-write & deduplication
 
 `memory add` does **not** unconditionally insert a new row. Before writing it:

package/assets/skill/references/onboarding.md

@@ -22,8 +22,8 @@ not touch git hooks.
 npx @lumoai/cli setup                    # interactive: prompts user/project; agent=claude-code
 npx @lumoai/cli setup --user             # write to ~/.claude/
 npx @lumoai/cli setup --project          # write to ./.claude/
-npx @lumoai/cli setup --force            # overwrite skill files if they differ from bundled
-npx @lumoai/cli setup --agent codex      # bake agent=codex into the hook commands
+lumo setup --project --force             # same via global install: overwrite skill files if they differ from bundled
+lumo setup --project --agent codex       # bake agent=codex into the hook commands
 ```
 
 Use when:

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

@@ -115,6 +115,11 @@ lumo task pr show LUM-42 128
 Read-only audit view over the task's `LineageEdge` rows. Given a task
 identifier (`LUM-N`), prints the causal trail:
 
+```bash
+lumo task lineage LUM-42            # per-session causal trail + cost
+lumo task lineage LUM-42 --signal   # append workspace-level usage signal-health
+```
+
 - **Totals banner** — distinct sessions, fragment count, edge count,
   total tokens (input/output/cache split) and loops, and the outcome
   distribution.

package/assets/skill/references/tasks.md

@@ -154,6 +154,13 @@ LUM-48  TODO         MEDIUM  backend    Investigate slow query
 | `-m, --milestone <ref>` | string  | Filter to my tasks under this milestone (name or UUID).                          |
 | `-n, --limit <count>`   | integer | Cap output to the first N rows.                                                  |
 
+```bash
+lumo task list                                  # everything assigned to me
+lumo task list --status in_progress -n 10       # capped, status-filtered
+lumo task list --project backend --status todo
+lumo task list --milestone "Q3 Launch"
+```
+
 When `--milestone` is set, the CLI calls `GET /api/milestones/<id>/tasks?assigned=me` instead of `/api/tasks/me`. Other filters (`--status`, `--limit`) still apply client-side to the milestone-scoped result.
 
 Filtering is currently client-side — the server returns the full "my tasks" set and the CLI slices it. This is fine for typical workspaces (dozens of tasks); revisit if a workspace has hundreds.

package/assets/skill/references/verify.md

@@ -146,3 +146,51 @@ major; additive fields don't. Pin on `version` when scripting against it.
 `status` reads; `verify` judges. Running status never starts a round, never
 escalates, and never changes task state — loop rules (cap 3, IN_REVIEW on
 all-pass, human-only DONE) live entirely in `lumo verify` and the server.
+
+## lumo verdict — the three verdict channels (LUM-422)
+
+`lumo verify` is the MACHINE channel. `lumo verdict` covers the other two — the
+HUMAN pass and the AGENT send-back — under one red line: **no passing data row
+is ever agent-produced.**
+
+```
+lumo verdict --pass
+lumo verdict LUM-42 --pass-with-followup
+lumo verdict --fail --reason CRITERION_UNMET --note "the retry path is still missing"
+lumo verdict LUM-42 --fail --reason scope_mismatch --criterion c-abc123
+```
+
+### --pass / --pass-with-followup — a deep link, never a write
+
+These resolve the task, then open the browser to its verdict bar focused on the
+passing action. **The CLI writes nothing** — PASS / PASS_WITH_FOLLOWUP only ever
+land from a human's own click (Clerk session). Use this to hand a finished task
+to a human for the final pass; it carries them one click from recording it.
+
+### --fail — the AGENT send-back
+
+`--fail --reason <enum>` records a real verdict row server-side with
+verifierType=AGENT (a channel distinct from MACHINE and HUMAN, so "machine
+all-pass but human FAIL" stays an uncontaminated signal). The verdict is
+hard-coded FAIL — there is no agent path to a passing verdict. It:
+
+- requires `--reason` (case-insensitive): `CRITERION_UNMET | EVIDENCE_INSUFFICIENT
+| CHECK_EXECUTION_ERROR | SCOPE_MISMATCH | OTHER` — the agent pays the
+  structured tax a human send-back is spared;
+- takes an optional `--note`, posted as a task comment (@mentions and images for
+  free) and summarized onto the verdict row;
+- takes repeatable `--criterion <id>` to narrow the send-back; omitted, it fans
+  out to the whole contract;
+- records at round = the current max (not a new round) and bounces the task back
+  to IN_PROGRESS, with the unmet criteria surfacing through `lumo task status`.
+
+### The DONE gate
+
+Once any criterion's latest verdict is FAIL — machine, AGENT, or human — moving
+the task to DONE on the agent/CLI path is refused with **409** and the
+unresolved items listed. Clear the send-back (fix + re-verify, or a human PASS)
+before `lumo task update <id> --status done`. A task with no criteria, or whose
+criteria were never adjudicated, transitions freely — the gate only blocks an
+actual send-back, never an un-adjudicated criterion. When the machine loop has
+left a task IN_REVIEW with no send-back standing, the agent may move it to DONE
+directly; a human-PASS row is a provable manual override, not a required ticket.

package/dist/cli/src/commands/verdict.js

@@ -0,0 +1,194 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.collectCriterion = collectCriterion;
+exports.verdict = verdict;
+const config_1 = require("../lib/config");
+const api_1 = require("../lib/api");
+const sanitize_1 = require("../lib/sanitize");
+const browser_1 = require("../lib/browser");
+/**
+ * Rejection-reason vocabulary (mirrors the server's VerificationRejectionReason
+ * enum). Required on the agent --fail path — the agent pays the structured tax
+ * a human is spared (LUM-422 ①).
+ */
+const FAIL_REASONS = [
+    'CRITERION_UNMET',
+    'EVIDENCE_INSUFFICIENT',
+    'CHECK_EXECUTION_ERROR',
+    'SCOPE_MISMATCH',
+    'OTHER',
+];
+/** Collect repeatable `--criterion <id>` flags into an array (commander idiom). */
+function collectCriterion(value, prev = []) {
+    return [...prev, value];
+}
+/**
+ * `lumo verdict [task]` — human + agent acceptance verdicts (LUM-422).
+ *
+ * Three modes, exactly one required:
+ *   --pass / --pass-with-followup  open the browser to the task's verdict bar,
+ *       focused on the passing action (a deep link — writes NOTHING; a passing
+ *       data row is only ever produced by a human's own click, red line).
+ *   --fail --reason <enum> [--note] [--criterion …]  records an AGENT send-back
+ *       (verdict hard-coded FAIL server-side) and bounces the task to
+ *       IN_PROGRESS. Bearer-authed.
+ *
+ * Defaults to the session-bound task; an explicit identifier overrides.
+ */
+async function verdict(identifier, options = {}) {
+    const modes = [
+        options.pass && 'pass',
+        options.passWithFollowup && 'pass-with-followup',
+        options.fail && 'fail',
+    ].filter(Boolean);
+    if (modes.length === 0) {
+        console.error('Error: choose a verdict mode — --pass, --pass-with-followup, or --fail.');
+        return 1;
+    }
+    if (modes.length > 1) {
+        console.error(`Error: pick exactly one verdict mode (got ${modes.join(', ')}).`);
+        return 1;
+    }
+    const creds = (0, config_1.readCredentials)();
+    if (!creds) {
+        console.error('Error: not logged in. Run `lumo auth login` first.');
+        return 1;
+    }
+    const base = (0, api_1.trimTrailingSlash)((0, api_1.resolveAuthedApiUrl)(creds.apiUrl));
+    const headers = {
+        Authorization: `Bearer ${creds.token}`,
+    };
+    const sessionId = process.env.CLAUDE_CODE_SESSION_ID;
+    if (sessionId)
+        headers['X-Lumo-Session-Id'] = sessionId;
+    // ── Resolve the task: explicit identifier or the session binding ──────────
+    let taskId = identifier;
+    if (!taskId) {
+        if (!sessionId) {
+            console.error('Error: no task given and $CLAUDE_CODE_SESSION_ID is not set.\n' +
+                'Run `lumo verdict <LUM-N> …` or run inside a session bound via `lumo session attach`.');
+            return 1;
+        }
+        let res;
+        try {
+            res = await fetch(`${base}/api/sessions/${encodeURIComponent(sessionId)}`, { headers });
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            console.error(`Error: could not reach Lumo API (${msg})`);
+            return 1;
+        }
+        const data = res.ok
+            ? (await res.json())
+            : null;
+        if (!data?.taskIdentifier) {
+            console.error('Error: this session is not bound to a task. Run `lumo session attach <LUM-N>` first, or pass the task explicitly.');
+            return 1;
+        }
+        taskId = data.taskIdentifier;
+    }
+    if (options.fail) {
+        return failVerdict(base, headers, taskId, options, creds.workspaceSlug);
+    }
+    return passDeepLink(base, headers, taskId, options.passWithFollowup ? 'pass_with_followup' : 'pass', creds.workspaceSlug);
+}
+/**
+ * --pass / --pass-with-followup: open the human's verdict bar pre-focused on the
+ * passing action. The CLI never writes the verdict — it only carries the human
+ * to the one click that does (red line: no agent-produced passing row).
+ */
+async function passDeepLink(base, headers, taskId, verdictParam, workspaceSlug) {
+    let res;
+    try {
+        res = await fetch(`${base}/api/tasks/by-identifier/${encodeURIComponent(taskId)}`, { headers });
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        console.error(`Error: could not reach Lumo API (${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 ${taskId} not found in workspace ${workspaceSlug}`);
+        return 1;
+    }
+    if (!res.ok) {
+        console.error(`Error: could not load task (HTTP ${res.status})`);
+        return 1;
+    }
+    const { task } = (await res.json());
+    if (!task?.url) {
+        console.error('Error: server did not return a task URL to open.');
+        return 1;
+    }
+    const sep = task.url.includes('?') ? '&' : '?';
+    const deepLink = `${task.url}${sep}verdict=${verdictParam}`;
+    const label = verdictParam === 'pass_with_followup' ? 'Pass with follow-up' : 'Pass';
+    process.stdout.write(`Opening ${taskId} for a human "${label}" verdict (nothing is recorded until they click):\n` +
+        `  ${(0, sanitize_1.sanitizeField)(deepLink)}\n`);
+    (0, browser_1.openBrowser)(deepLink);
+    return;
+}
+/**
+ * --fail: record an AGENT send-back. The server hard-codes verdict=FAIL and
+ * verifierType=AGENT — there is no passing verdict the CLI can express.
+ */
+async function failVerdict(base, headers, taskId, options, workspaceSlug) {
+    if (!options.reason) {
+        console.error(`Error: --fail requires --reason <${FAIL_REASONS.join('|')}>.`);
+        return 1;
+    }
+    // Case-insensitive like every other CLI enum flag (LUM-420): fold to the
+    // canonical upper-case enum before validating and sending.
+    const reason = options.reason.toUpperCase();
+    if (!FAIL_REASONS.includes(reason)) {
+        console.error(`Error: invalid --reason "${options.reason}". Allowed: ${FAIL_REASONS.join(', ')}.`);
+        return 1;
+    }
+    const body = { rejectionReasonEnum: reason };
+    if (options.note)
+        body.note = options.note;
+    if (options.criterion && options.criterion.length > 0) {
+        body.criterionIds = options.criterion;
+    }
+    let res;
+    try {
+        res = await fetch(`${base}/api/tasks/${encodeURIComponent(taskId)}/agent-verdict`, {
+            method: 'POST',
+            headers: { ...headers, 'Content-Type': 'application/json' },
+            body: JSON.stringify(body),
+        });
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        console.error(`Error: could not reach Lumo API (${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 ${taskId} not found in workspace ${workspaceSlug}`);
+        return 1;
+    }
+    if (!res.ok) {
+        const errBody = (await res.json().catch(() => null));
+        const detail = errBody && typeof errBody.error === 'string'
+            ? (0, sanitize_1.sanitizeField)(errBody.error)
+            : '';
+        console.error(`Error: send-back rejected (HTTP ${res.status})${detail ? ` — ${detail}` : ''}`);
+        return 1;
+    }
+    const outcome = (await res.json());
+    process.stdout.write(`✗ Sent ${taskId} back (AGENT FAIL, reason ${reason}) — ` +
+        `${outcome.criterionIds.length} ${outcome.criterionIds.length === 1 ? 'criterion' : 'criteria'} at round ${outcome.round}; task is now ${outcome.taskStatus}.\n`);
+    if (outcome.commentId) {
+        process.stdout.write('  A send-back note was posted as a task comment.\n');
+    }
+    process.stdout.write('Address the unmet criteria (see `lumo task status`), then re-verify.\n');
+    return;
+}

package/dist/cli/src/index.js

@@ -49,6 +49,7 @@ const session_status_1 = require("./commands/session-status");
 const session_wrap_1 = require("./commands/session-wrap");
 const next_1 = require("./commands/next");
 const verify_1 = require("./commands/verify");
+const verdict_1 = require("./commands/verdict");
 const task_context_1 = require("./commands/task-context");
 const task_create_1 = require("./commands/task-create");
 const task_update_1 = require("./commands/task-update");
@@ -218,6 +219,16 @@ program
     .description('Machine verification loop (LUM-343): run every MACHINE criterion checkpointer locally, report structured verdicts to the server (round cap 3), and print next actions. All-pass moves the task to IN_REVIEW. Defaults to the session-bound task.')
     .option('--timeout <seconds>', 'Per-checkpointer timeout in seconds (default 600)')
     .action(wrap((task, options) => (0, verify_1.verify)(task, options)));
+program
+    .command('verdict [task]')
+    .description('Acceptance verdict (LUM-422). --pass / --pass-with-followup open the browser to the human verdict bar focused on the passing action (a deep link — records nothing; a passing row is only ever a human click). --fail --reason <enum> records an AGENT send-back and bounces the task to IN_PROGRESS. Defaults to the session-bound task.')
+    .option('--pass', 'Open the verdict bar focused on Pass (human one-click; no write)')
+    .option('--pass-with-followup', 'Open the verdict bar focused on Pass with follow-up (human one-click; no write)')
+    .option('--fail', 'Record an AGENT send-back (verdict FAIL) — requires --reason')
+    .option('--reason <enum>', 'Rejection reason for --fail: CRITERION_UNMET | EVIDENCE_INSUFFICIENT | CHECK_EXECUTION_ERROR | SCOPE_MISMATCH | OTHER (case-insensitive)')
+    .option('--note <text>', 'Optional send-back narrative, posted as a task comment')
+    .option('--criterion <id>', 'Narrow a --fail to specific criteria (repeatable); omitted = the whole contract', verdict_1.collectCriterion)
+    .action(wrap((task, options) => (0, verdict_1.verdict)(task, options)));
 program
     .command('next')
     .description('Recommend the next task(s) to work on, ranked by priority, active sprint, and due date. Prints top N (default 3); pick one and run `session attach` + `task context`.')

package/package.json

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