@lumoai/cli 1.29.0 → 1.29.1

package/assets/skill/SKILL.md

@@ -0,0 +1,163 @@
+---
+name: lumo
+description: 'Use the Lumo CLI to work with Lumo (project management for dev teams) from the terminal: load task context, bind/wrap Claude Code sessions, and create/update/list/show/comment on tasks, projects, milestones, sprints, documents, artifacts, Figma links, dependencies, and team memory — plus acceptance criteria, machine verification (verify / task status), lineage audit, worktree scaffolding, and CLI setup/auth/update. Activate when the user mentions a Lumo task identifier (LUM-N) or the lumo CLI, in any language; asks to load task background or bind/check/wrap a session; manages any of the resources above in Lumo; is starting, resuming, or about to claim completion of a task; or asks what to work on next. Key triggers: "LUM-", "lumo", "task context", "session attach", "session wrap", "verify", "task status", "acceptance criteria", "milestone", "sprint", "docs", "memory", "deps", "lineage", "worktree", "design link", "what should I work on", "resume task".'
+---
+
+## Prerequisites
+
+Before running any `lumo` command, verify the CLI is available and authenticated:
+
+```bash
+which lumo && lumo whoami
+```
+
+- If `lumo` is not found: tell the user to install it (`npm install -g @lumoai/cli`; for monorepo dev, `cd cli && npm install && npm link` also works)
+- If `lumo whoami` fails with an auth error: tell the user to run `lumo auth login`
+- Do NOT proceed with any lumo commands until both checks pass
+
+## How this skill is organized
+
+The command catalog below is a **map**: it lists every command grouped by domain with a one-line summary. **Detailed flags, examples, output formats, and "when to suggest" guidance live in the `references/` files** — when a user request lands in a domain, **Read the matching reference file before composing the command**. Don't run a command from memory if its flags/edge-cases matter; open the reference first.
+
+| Domain                                                                                  | Read this reference                                            |
+| --------------------------------------------------------------------------------------- | -------------------------------------------------------------- |
+| `setup`, `auth login/logout`, `whoami`, `update`                                        | [references/onboarding.md](references/onboarding.md)           |
+| `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)               |
+| `verify`, `task status` — machine verification loop, claim-done flow, self-check/resume | [references/verify.md](references/verify.md)                   |
+| `project list`, `milestone*`                                                            | [references/milestones.md](references/milestones.md)           |
+| `doc*`                                                                                  | [references/docs.md](references/docs.md)                       |
+| `sprint*`                                                                               | [references/sprints.md](references/sprints.md)                 |
+| `task/project memory`, `memory promote/rm`                                              | [references/memory.md](references/memory.md)                   |
+| `session attach/status/detach/wrap`, git-suggest on start, Layer-2 review               | [references/sessions.md](references/sessions.md)               |
+| `worktree add/rm/list` (local dev tooling)                                              | [references/worktree.md](references/worktree.md)               |
+
+## Command catalog
+
+**Onboarding / auth / update** — see [onboarding.md](references/onboarding.md)
+
+- `lumo setup [--user|--project] [--force] [--agent <token>]` — install skill files + hooks
+- `lumo auth login` / `lumo auth logout` — paste an API key / clear credentials
+- `lumo whoami` — show current identity (email, workspace, key)
+- `lumo update` — upgrade the CLI to the latest npm release
+
+**Task context & retrieval** — see [task-context.md](references/task-context.md)
+
+- `lumo task context <id>` — load task background (memory, source cards, PR review todos, prior sessions)
+- `lumo task slack show <id> <contextId>` — full stored Slack thread
+- `lumo task web show <id> <linkId>` — fetched web link body
+- `lumo task figma context <id> <linkId>` — Figma link metadata (v1)
+- `lumo task comments list <id>` — full comment thread (read-only; ≠ `task comment`)
+- `lumo task pr show <id> <number>` — synced PR metadata (v1)
+- `lumo task lineage <id>` — show the causal trail: fragments that fed the task + each one's outcome + the run's token/loop cost (read-only audit view); `lumo task lineage <id> --signal` also appends workspace-level usage signal-health (used distribution, per-session variance, used-vs-base merge rate)
+
+**Tasks** — see [tasks.md](references/tasks.md)
+
+- `lumo task create <title> [flags]` — create a task
+- `lumo task update <id> [flags]` — patch status/title/priority/assignee/milestone/sprint/tags
+- `lumo task list [flags]` — list tasks assigned to you
+- `lumo next [--count N]` — recommend the next task to work on (read-only)
+- `lumo task show <id>` — print one task's detail
+- `lumo task comment <id> <body>` — leave a comment
+
+**Task dependencies**
+
+- `lumo task deps list <id>` — list dependency edges in both directions, grouped CONFIRMED / SUGGESTED (pending confirmation) / DISMISSED; each row shows a short edge id `[xxxxxxxx]`, the other task, and detected evidence (`shared_files(N shared files: …)` / `task_mention(…)`); SUGGESTED rows include a copy-pasteable confirm hint
+- `lumo task deps add <id> --blocked-by <LUM-N>` — declare a manual hard dependency (created CONFIRMED, source MANUAL; if a SUGGESTED/DISMISSED edge already exists in the same direction, it is confirmed in place rather than creating a new row)
+- `lumo task deps confirm <id> <edge> [--reverse]` — confirm a detected candidate; `<edge>` is a short edge-id prefix (≥6 chars) or the other task's identifier (case-insensitive); `--reverse` flips the direction when the detector guessed it backwards
+- `lumo task deps dismiss <id> <edge>` — dismiss a candidate (never re-suggested)
+- `lumo task deps rm <id> <edge> --yes` — delete an edge (refuses without `--yes`)
+- On an ambiguous/unknown `<edge>` selector the CLI prints all candidates with short ids and exits 1 — retry with one of them
+
+**Acceptance criteria (contract)** — see [criteria.md](references/criteria.md)
+
+- `lumo task criteria set <task> --file <criteria.json> [--human] [--cause <tag>]` — 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); `--cause` (with `--human`) annotates why the contract drifted: `NEW_INFO | SCOPE_CHANGE | DRAFT_BLIND_SPOT | GRANULARITY | OTHER`
+- `lumo task criteria list <task>` — print the contract (id, MACHINE/HUMAN, provenance source@round, checkpointer)
+
+**Verification (machine acceptance loop)** — see [verify.md](references/verify.md)
+
+- `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.**
+
+**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
+- `lumo task figma add/list/rm/refresh` — attach & manage Figma designs
+
+**Projects & milestones** — see [milestones.md](references/milestones.md)
+
+- `lumo project list` — list projects (slugs feed `--project`)
+- `lumo milestone list/create/show/update/delete` — milestone CRUD (`show` includes a Sprint-coverage section)
+- `lumo milestone archive/unarchive` — soft-archive / restore
+- `lumo milestone add/remove <id> <task...>` — batch bind/unbind tasks
+- `lumo milestone summary [--retry]` — AI retro
+- `lumo milestone reorder/move` — manual ordering
+
+**Documents** — see [docs.md](references/docs.md)
+
+- `lumo doc create/update/show/list/delete` — document CRUD; `doc show` prints the body revision, `doc update` takes `--if-revision <n>` (mismatch → 409 conflict, re-read and retry — no silent overwrite)
+- `lumo doc show <doc> --raw` — print the byte-identical markdown source of the last markdown upload (the only legal edit base; errors when no source is stored — never falls back to the lossy HTML→md render)
+- `lumo doc show <doc> --section "<heading>"` — print just one heading-addressed section of the markdown source (byte-faithful slice, subsections included; revision on stderr; prefix `#…` pins depth)
+- `lumo doc patch <doc> --section "<heading>" --content/--file/stdin [--if-revision N]` — replace ONLY that section (heading line included); every byte outside it is untouched; concurrent edits 409 instead of clobbering
+- `lumo doc append <doc> [--section "<heading>"] --content/--file/stdin [--if-revision N]` — append at section end (or doc end without `--section`); pure insertion, no existing byte modified — the safest write for running logs/ledgers
+- `lumo doc diff <doc> --file <local.md>` — compare the server-side markdown source against a local file (exit 0 identical, 1 with unified diff)
+- `lumo doc move` — reparent under a parent / to root
+- `lumo doc bind/unbind <doc> <task>` — task linkage
+- `lumo doc share/unshare/share-list` — member sharing
+- `lumo doc import-gdoc` / `lumo doc sync` — Google Doc import & re-sync
+
+**Sprints** — see [sprints.md](references/sprints.md)
+
+- `lumo sprint list/create/show/update/delete` — sprint CRUD (`show` includes Progress / Health / Blockers)
+- `lumo sprint start/close` — status transitions (no `--status` flag)
+- `lumo sprint add/remove <id> <task>` — bind/unbind a task
+- `lumo sprint summary [--retry]` — AI retro
+
+**Memory** — see [memory.md](references/memory.md)
+
+- `lumo task memory add/list` · `lumo project memory add/list` — record/curate Memory (TASK vs PROJECT)
+- `lumo memory promote <id>` / `lumo memory rm <id> --yes` — TASK→PROJECT / delete
+
+**Sessions** — see [sessions.md](references/sessions.md)
+
+- `lumo session attach <id>` — bind this session to a task (then run `task context`)
+- `lumo session status` / `lumo session detach` — show / clear binding
+- `lumo session wrap [--yes] [--dry-run] [--used <indices>]` — end-of-session panel: progress comment + memory review + fragment-usage vote (`--used`, LUM-300) + blocked-tag prompt. Usage is now also audited automatically when a task reaches DONE (evidence-gated, true-only — confident fragments marked used, the rest left NULL); `session wrap --used` remains the manual override and takes precedence for a session.
+- Git-suggest at session start (suggests `session attach`, never auto-binds) + Layer-2 project-memory review — see the reference
+
+**Worktrees (local dev tooling)** — see [worktree.md](references/worktree.md)
+
+- `lumo worktree add <LUM-N> [slug]` — scaffold `.worktrees/<LUM-N>` + node_modules symlink off origin/main; run from the main checkout
+- `lumo worktree rm <LUM-N> --yes` — remove a worktree (keeps the branch unless `--delete-branch`)
+- `lumo worktree list` — list `.worktrees/` worktrees (task id, branch, dirty, node_modules link)
+
+## Commands & flags that do NOT exist (common mistakes)
+
+Measured from real agent sessions (LUM-392) — don't guess these:
+
+- No `lumo session start` — binding is `lumo session attach <LUM-N>`
+- No `lumo task delete` — tasks can't be deleted from the CLI (web UI only)
+- No `lumo task artifact edit` — it's `lumo task artifact update`
+- No `lumo auth status` — identity check is `lumo whoami`
+- No `--body` on `lumo task comment` — the body is a positional arg: `lumo task comment LUM-N "text"`
+- No `--content` on `task/project memory add` — memory is structured fields (`--category` + per-category flags), see [memory.md](references/memory.md)
+- No global `--verbose` flag on any command
+- `lumo task comments list` (plural) **reads** the thread; `lumo task comment` (singular) **writes** one
+- Status updates: `lumo task update LUM-N --status done` is one direct call — do **not** walk `in_progress → in_review → done` step by step (see [tasks.md](references/tasks.md) for the transition matrix; under the verify flow you shouldn't be setting `in_review`/`done` yourself at all)
+
+## Core workflow
+
+Typical flow when a user says "help me with LUM-42":
+
+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. **If the task has no acceptance criteria** (context shows the draft reminder instead of a contract): draft outcome-level criteria sized to the task (3–7 for a typical multi-file task; 1–2 for a micro task) 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
+6. **Before claiming the work is done: run `lumo verify`** — the machine half of the acceptance loop. Fix failures and re-run (round cap 3). On all-pass the task moves to IN_REVIEW and you stop; never set DONE yourself after a verify loop — that adjudication is human-only. See [verify.md](references/verify.md)
+
+**Status-first recovery:** when you pick a task back up — a new session resuming earlier work, or a task that came back after a rejected verification round / review findings — run `lumo task status` **before** re-reading code or planning. It tells you where the loop stands (current round, what passed, what's unmet and why, any REVIEW_ADDED criteria appended during review) so you don't redo finished work or miss the reason it bounced. See [verify.md](references/verify.md)
+
+**Git-suggest at start:** when the session is unbound, session-start may infer the task from the git branch / recent commits (any team prefix, e.g. `SPEC-12`, not just `LUM-N`) and print a suggestion — `Detected LUM-N (from branch name). Run lumo session attach LUM-N to bind.` (or `from recent commits`) — **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/artifacts-figma.md

@@ -0,0 +1,124 @@
+# Task Artifacts & Figma Designs
+
+### Task ↔ Spec Artifacts
+
+Record Claude Code spec-engineering products (spec / plan / design …) on a task. The artifacts show up in the task detail definition ("spec") layer and are injected into `lumo task context`.
+
+#### `lumo task artifact add <task> --kind <kind> --title <title> --file <path> --source <source> --agent <agent>`
+
+Attaches an artifact to a task. `--kind`, `--title`, `--source` are stored verbatim — **`kind` is opaque** (no enumeration; `spec` / `plan` / `requirements` / anything is accepted). `--source` is **required** and names the spec-generation framework that produced the artifact, written as its **formal name** (`Superpowers` / `Spec Kit` / `BMad` / `OpenSpec` / `GSD` / …) — it is also opaque (no enumeration), but there is **no default**, so you must pass it. Quote names that contain spaces (`--source "Spec Kit"`). `--file` supplies the body (file contents). Each call appends to the end of the task's artifact list — call once per artifact (e.g. Superpowers: one `spec`, one `plan`). The `<task>` (e.g. `LUM-42`) is resolved server-side. **`--file` is sandboxed:** the CLI rejects any path that resolves **outside the current project directory** (parent-traversal, absolute paths, escaping symlinks) or that matches a **sensitive-file denylist** (`.env*`, `id_rsa`/`id_ed25519`, `*.pem`/`*.key`, `.aws`/`.ssh` contents, `credentials`, `.npmrc`, …). There is no override flag — pass only project-local, non-secret files (e.g. `docs/spec.md`). To record an out-of-tree file, copy it into the project first.
+
+`--agent` is **required** and names the coding tool that produced the artifact (enum). Valid values: `claude-code | codex | cursor | gemini-cli | github-copilot | windsurf` (case-insensitive; `gemini` and `copilot` are accepted aliases).
+
+```bash
+lumo task artifact add LUM-42 --kind spec --title "Spec" --file docs/spec.md --source Superpowers --agent claude-code
+lumo task artifact add LUM-42 --kind plan --title "Implementation plan" --file docs/plan.md --source "Spec Kit" --agent claude-code
+```
+
+Output: `Added [spec] "Spec" to LUM-42`
+
+#### `lumo task artifact update <task> <artifact-id> [--kind <kind>] [--title <title>] [--source <source>] [--agent <agent>]`
+
+Patches an existing artifact's metadata in place. Editable fields are **`kind`, `title`, `source`, and `agent`** — **content is immutable** (to change the body, `rm` the artifact and `add` it again). At least one flag is required; passing none errors before any network call. Empty values (`--kind ""`) are rejected. The `<artifact-id>` is the cuid in column 1 of `artifact list`. `--agent` accepts the same valid values and aliases as `artifact add`: `claude-code | codex | cursor | gemini-cli | github-copilot | windsurf` (case-insensitive; `gemini` and `copilot` are accepted aliases).
+
+```bash
+lumo task artifact update LUM-42 cma_xxx --kind plan              # re-classify spec → plan
+lumo task artifact update LUM-42 cma_xxx --source "Spec Kit"      # fix the framework label
+lumo task artifact update LUM-42 cma_xxx --title "Final spec" --source OpenSpec
+lumo task artifact update LUM-42 cma_xxx --agent cursor           # fix the agent label
+```
+
+Output: `Updated [plan] "Final spec" (OpenSpec) on LUM-42`. A 404 (task or artifact missing in this workspace) prints the server message and exits 1.
+
+#### `lumo task artifact list <task>`
+
+Lists artifacts on the task in order: `<id>  <kind>  <agent>  <source>  <title>`. Prints `No artifacts on <task>` when there are none.
+
+```bash
+lumo task artifact list LUM-42
+```
+
+#### `lumo task artifact show <task> <artifact-id>`
+
+Prints one artifact's key:value header (id, kind, title, agent, source, order, task) followed by the full content body. The `<artifact-id>` is the cuid in column 1 of `artifact list`.
+
+```bash
+lumo task artifact show LUM-42 cma_xxx
+```
+
+#### `lumo task artifact rm <task> <artifact-id> --yes`
+
+Deletes an artifact from a task. Irreversible — `--yes` is required and there is no interactive prompt (agent-friendly). On success prints `Removed <artifact-id> from <task>`. A 404 (task or artifact missing in this workspace) prints the server message and exits 1.
+
+```bash
+lumo task artifact rm LUM-42 cma_xxx --yes
+```
+
+When to suggest: after running a spec/plan workflow in Claude Code, offer to record the product(s) with `task artifact add` (one call per artifact) — always pass `--source` with the framework you used. Use `task artifact list` to see what's already recorded, `task artifact show` to inspect a single artifact's content, `task artifact update` to fix a wrong kind/title/source without re-uploading, and `task artifact rm` to drop one that's wrong or stale.
+
+### Task ↔ Figma Designs
+
+#### `lumo task figma add <task> <url>` — attach a Figma file/frame
+
+Fetches file name, frame name, and thumbnail via Figma OAuth and stores them
+on the task.
+
+```bash
+lumo task figma add LUM-42 "https://www.figma.com/design/abc123/Onboarding?node-id=1-234"
+```
+
+If the URL omits `node-id`, the link is stored as file-level; the CLI prints
+a `(file-level, thumbnail from "...")` note showing the auto-picked
+representative frame.
+
+Idempotent — re-adding the same URL within 7 days returns the existing row
+without re-calling Figma.
+
+**Not connected?** Errors with:
+
+```
+✗ You haven't connected Figma yet.
+  Run: open https://www.uselumo.ai/settings/integrations
+```
+
+#### `lumo task figma list <task>` — list attachments
+
+```
+$ lumo task figma list LUM-42
+cfl_xxx1  Onboarding       Welcome screen       2026-05-28
+cfl_xxx2  Design System    Button / Primary     2026-05-27
+cfl_xxx3  Onboarding       (file-level)         2026-05-20  ⚠ thumbnail stale
+```
+
+`⚠ thumbnail stale` appears when `thumbnailFetchedAt > 25 days`.
+
+#### `lumo task figma rm <task> <link-id-or-url>` — remove an attachment
+
+Accepts a `cfl_*` cuid or the original URL. Idempotent (`Not linked: ...` + exit 0 when no match).
+
+#### `lumo task figma refresh <task>` — manual refresh
+
+Re-fetches metadata + thumbnail for every Figma link on the task. Per-link
+failures are isolated.
+
+```
+$ lumo task figma refresh LUM-42
+Refreshed 3 Figma links on LUM-42
+  ✓ Onboarding · Welcome screen
+  ✓ Onboarding · Sign-up form
+  ✗ Design System · Button (file not accessible)
+```
+
+### When to suggest the `task figma` commands
+
+- User pastes a Figma URL or mentions a design ("here's the mock", "the
+  Figma is at...").
+- User asks "what designs are linked to this task" or "show me the Figma
+  for LUM-42".
+- After implementing a UI change, suggest `lumo task figma refresh <task>`
+  if the user mentioned updating the Figma source.
+
+OAuth connection lives in the Web UI at
+`/settings/integrations`. The CLI does **not** have a `figma auth`
+command; if the user tries `task figma add` without connecting, the error
+message directs them to the Web UI.

package/assets/skill/references/criteria.md

@@ -0,0 +1,160 @@
+# Acceptance criteria (contract)
+
+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 task #3) judge against it. Criteria are injected at session start and
+in `lumo task context` as the `## Acceptance criteria (contract)` 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 the draft reminder ("This task
+has no acceptance criteria yet. …") 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** for a typical multi-file task (soft range — the
+   server warns outside it but never rejects; if you genuinely need more,
+   merge related checks instead). **Scale the count down for small tasks** —
+   see "Scale the contract to the task size" below.
+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.
+
+## Scale the contract to the task size
+
+The 3–7 range is calibrated for typical multi-file tasks. The criterion count
+must track the size of the work — it is not a fixed ritual:
+
+- **Micro task** (expected to fit a single session, blast radius of one or
+  two files — a docs tweak, a copy change, a small targeted fix): **1–2
+  criteria IS a complete contract** — one targeted MACHINE criterion plus at
+  most one HUMAN criterion.
+- **Never pad toward the soft floor.** A filler criterion (a restated
+  baseline, a third angle on the same check) dilutes the contract and taxes
+  every verification round. For a micro task the below-minimum warning is
+  expected — ignore it.
+- **Shrink the contract, never skip it.** Every task still drafts and locks a
+  contract before the first line of code; task size only changes how many
+  criteria that takes.
+
+## 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 (execution on the client, adjudication on 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 origin
+(`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.
+
+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
+draft missed it, wrong granularity). The tag lands in the drift record
+(TaskActivity payload), feeding the Slice-3 drift-cause distribution. Every
+criteria add/update/delete is mirrored as a structured `CRITERION_CHANGED`
+activity automatically; `--cause` just enriches it.
+
+### `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, the draft reminder is injected instead.
+- **`lumo session attach`**: prints the contract (or the draft reminder) right after
+  binding.
+- **`lumo task context`**: the `## Acceptance criteria (contract)` section appears after the
+  task description, before memory.
+- Review-time gap findings are appended at the round they surface and show up
+  in the contract automatically — `REVIEW_ADDED` provenance via human review
+  paths; findings a human raises in conversation are transcribed with
+  `--human` + `--cause` (see verify.md "Review-time drift habits").
+
+## After the contract: the verification loop
+
+The contract is judged by `lumo verify` — run it before claiming the task is
+done. See [verify.md](verify.md) for the loop (round cap 3, IN_REVIEW on
+all-pass, escalation on a round-3 fail).