@lumoai/cli 1.30.0 → 1.32.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

@@ -64,9 +64,84 @@ must track the size of the work — it is not a fixed ritual:
     HUMAN** — the server rejects checkpointer-less MACHINE criteria rather
     than silently rewriting them. Don't invent a fake checkpointer to keep it
     MACHINE.
+  - **Jest-by-name checkpointers must go through the zero-match guard.** A
+    bare `npx jest -t '<name>'` exits 0 even when the pattern matches **no**
+    test — rename or delete the test and the checkpointer silently fake-PASSes
+    (same trap class as the BSD-grep `-P` incident, LUM-401). Write
+    `npx tsx scripts/jest-t.ts '<exact test name>' [test file path]` instead:
+    it fails unless ≥1 matching test ran and passed. The optional path scopes
+    the run to one file (much faster than name-filtering the whole suite).
 - `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 +179,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 +207,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 +226,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

@@ -2,6 +2,34 @@
 
 ## Document Management
 
+### Content channels: prefer stdin / `--content`
+
+`doc create` / `doc update` / `doc patch` / `doc append` all take the body from one of three mutually-exclusive channels. **For agent write-back, prefer stdin or `--content`** — pipe the markdown you already hold in memory, or pass it inline:
+
+```bash
+printf '%s' "$body" | lumo doc update cmd_xxx                                 # stdin — best for multi-line / generated content
+lumo doc append cmd_xxx --section "F 待办队列" --content "- [ ] 评估 XYZ 论文"   # --content — short inline edits
+```
+
+`--file` is the **fallback for content that already lives in an authoritative file on disk** (e.g. a repo-tracked `docs/live-docs/<file>.md` source you are editing). It is **not** the default channel: `--file` is sandboxed — the CLI rejects any path outside the current project directory or matching the sensitive-file denylist (`.env*`, keys, `credentials`, …), with no override. So feeding it generated content forces you to first write a scratch file _inside the repo_ just to pass it — an extra step that is the real-world friction that gets `--file` rejected. Pipe via stdin instead and skip the temp file; reach for `--file` only when the file _is_ the source of truth you're editing.
+
+### Markdown tables: keep them compact (no alignment padding)
+
+When you author or edit a markdown doc that contains tables (live-docs, registers, reports), write the cells **compact — one space around each pipe, no column-alignment padding**:
+
+```
+| col | meaning |
+| --- | --- |
+| a | first |
+```
+
+not the aligned form (`| col   | meaning |` padded so columns line up). Two reasons, both about local editability:
+
+- **prettier re-pads tables.** A compact table gets re-aligned and a padded one churns the diff on every prettier run — so repo-tracked live-doc sources under `docs/live-docs/` are in `.prettierignore` to stay byte-stable (see the live-docs README).
+- **the Edit tool's exact-match fails on padding.** Incremental edits match on exact cell text; alignment whitespace makes that match fragile (measured to fail). Compact cells edit reliably.
+
+This is a pure authoring convention — the server stores your markdown **byte-for-byte** (`sourceMarkdown`), so `doc show --raw` and `doc diff` stay byte-exact (LUM-408); there is **no** server-side table normalization to lean on. The structure guard (LUM-410) compares _rendered_ structure and is whitespace-insensitive, so compactness buys local editability, not a verify pass.
+
 ### `lumo doc create [title] [flags]` — create a new document
 
 Use this when the user wants to write a new document from the terminal. Title is positional and optional. When omitted, the doc title defaults to empty (server renders as "Untitled" via i18n).
@@ -132,12 +160,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 +192,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 +216,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 +306,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/assets/skill/references/worktree.md

@@ -10,9 +10,11 @@ there); `list` is read-only and runnable from anywhere.
 
 Creates `.worktrees/<LUM-N>[-slug]` on branch `lumo/<LUM-N>[-slug]`, branched off
 `origin/main` (after a fetch), and symlinks its `node_modules` to the main
-checkout so jest/tsc work immediately. With no slug, the dir and branch use the
-bare `LUM-N` form. Prints next-step guidance plus the two gotchas it can't fix
-for you (shared prisma client, jest cwd).
+checkout so jest/tsc work immediately. In the same scaffold step it copies the
+main checkout's `.husky/_` hooks shim into the worktree so git hooks actually
+fire there (see below). With no slug, the dir and branch use the bare `LUM-N`
+form. Prints next-step guidance plus the two gotchas it can't fix for you
+(shared prisma client, jest cwd).
 
 ```bash
 lumo worktree add LUM-267 worktree-scaffold   # → .worktrees/LUM-267-worktree-scaffold
@@ -36,6 +38,19 @@ do `generate + tsc` atomically once at the end.
 in first) — `cli/` has no jest config, and running from the main checkout hits
 the `cli/package.json` haste collision and silently runs the wrong tests.
 
+**The husky hooks it copies in:** husky owns git hooks via
+`core.hooksPath = .husky/_`, a relative path git resolves against each
+worktree's own root. That `_` shim dir is **untracked** (husky regenerates it on
+the main checkout's `npm install`/`prepare`), so a fresh worktree would lack it
+and git would **silently skip every hook** — pre-commit (lint-staged) and
+commit-msg (LUM-405 drift-check) included. Since this repo has no GitHub CI,
+husky is the only deterministic quality gate, so `add` copies `.husky/_` into the
+new worktree (copy, not symlink — the shim is tiny and the hooks it invokes
+resolve relative to the worktree). If the main checkout itself has no `.husky/_`
+(husky never installed there), `add` prints a warning telling you to run
+`npm install` in the main checkout to regenerate it, rather than skipping
+silently.
+
 **Never run `npm install` / `npm ci` inside a worktree.** The worktree shares
 the main checkout's `node_modules` via a symlink; npm does not respect the link
 — it deletes it and reifies a full standalone `node_modules` (thousands of

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/commands/worktree-add.js

@@ -96,6 +96,23 @@ async function worktreeAdd(rawId, slug, opts) {
     else {
         console.log('Warning: main checkout has no node_modules; run `npm install` there, then symlink manually');
     }
+    // husky owns git hooks via `core.hooksPath = .husky/_` (a relative path git
+    // resolves against each worktree's root). That `_` shim dir is untracked
+    // (generated by husky on the main checkout's `npm install`/`prepare`), so a
+    // fresh worktree lacks it and git SILENTLY skips every hook — pre-commit
+    // (lint-staged) and commit-msg (LUM-405 drift-check) included. This repo has
+    // no CI, so husky is the only deterministic gate; copy the shim in so hooks
+    // fire. Copy (not symlink) is the stable choice: the shim is tiny, rarely
+    // changes, and the hooks it invokes resolve relative to the worktree.
+    const srcHusky = path.join(root, '.husky', '_');
+    if (fs.existsSync(srcHusky)) {
+        fs.cpSync(srcHusky, path.join(dir, '.husky', '_'), { recursive: true });
+        console.log('  git hooks:     husky shim copied (pre-commit + commit-msg active)');
+    }
+    else {
+        console.log('Warning: main checkout has no .husky/_ shim; git hooks will NOT run in this worktree.');
+        console.log('          Run `npm install` in the main checkout to (re)generate husky, then re-run `lumo worktree add`.');
+    }
     printGuidance(dir, branch);
     if (opts.verify) {
         console.log('Running baseline jest …');

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.32.0",
   "description": "Lumo CLI — manage tasks and sessions from the terminal",
   "license": "MIT",
   "author": "cli@uselumo.ai",