@lumoai/cli 1.29.0 → 1.29.1

package/assets/skill/references/verify.md

@@ -0,0 +1,148 @@
+# lumo verify — machine verification loop
+
+`lumo verify` is the machine half of the acceptance system (Acceptance v1,
+LUM-343). It executes every **MACHINE** criterion's checkpointer in the local
+repo, reports one structured PASS/FAIL verdict per criterion to the server,
+and prints what to do next. The judge lives server-side: round numbering, the
+3-round cap, escalation, and the IN_REVIEW transition all happen there
+(execution on the client, adjudication on the server).
+
+## The claim-done rule
+
+**Before claiming a task is complete — in conversation, in a wrap-up, or by
+touching its status — run `lumo verify`.** The loop replaces "I read the code
+and it looks done" with executed evidence.
+
+```
+lumo verify              # session-bound task
+lumo verify LUM-42       # explicit task (overrides the session binding)
+lumo verify --timeout 900  # per-checkpointer timeout in seconds (default 600)
+```
+
+## What one round does
+
+1. Loads the task's acceptance contract and picks out MACHINE criteria.
+2. Runs each checkpointer locally (shell, cwd = current directory), one at a
+   time, echoing PASS/FAIL as it goes.
+3. POSTs the structured verdicts; the server records one VerificationRun per
+   criterion at round = previous max + 1 and mirrors each verdict as a
+   TaskActivity event.
+4. Prints the round outcome:
+   - **All PASS** → the task transitions to **IN_REVIEW** (existing state
+     machine + TASK_IN_REVIEW notification). **Stop here.** Human
+     adjudication and any HUMAN criteria take over; never set DONE yourself.
+   - **Any FAIL** → task status is untouched; the unmet criteria are printed
+     as next actions (statement, checkpointer, failure tail). Fix and re-run.
+   - **Round 3 still failing** → the loop escalates: a human is notified
+     (AGENT_VERIFY, requires action) and further `lumo verify` rounds are
+     rejected with 409. **Stop retrying**; fix only what the human directs.
+
+Exit code 0 = all passed (or nothing to run); 1 = failures, escalation, or
+errors.
+
+## Verdict semantics (what the CLI sends)
+
+- checkpointer exits 0 → `PASS` with evidence `cmd:<command>#exit=0`
+- non-zero exit → `FAIL`, reason = output tail, enum `CRITERION_UNMET`
+- spawn failure / timeout → `FAIL`, enum `CHECK_EXECUTION_ERROR`
+
+evidencePointer is **not free text** — the server only accepts
+`commit:<hash>`, `file:<path>:<line>`, or `cmd:<command>#exit=<code>`.
+Verdicts are PASS|FAIL only; the agent path cannot write HUMAN verdicts or
+`PASS_WITH_FOLLOWUP` (red line — those enter via human-initiated UI paths
+only).
+
+## Edge cases
+
+- **No contract yet** → error pointing at `lumo task criteria set`; draft the
+  contract first (criteria.md golden rule).
+- **HUMAN-only contract (zero MACHINE criteria)** → nothing to run; the CLI
+  says so and suggests handing off for human review
+  (`lumo task update <id> --status in_review`). No server write happens.
+- **A round must cover every MACHINE criterion** — the CLI always runs all of
+  them; the server rejects partial rounds.
+- Criteria added during review (`REVIEW_ADDED`) appear in the contract and
+  are picked up automatically by the next round.
+
+## Round discipline
+
+Rounds are a hard budget of 3, not a retry loop. Between rounds, actually fix
+the failures — re-running without changes burns a round and (at round 3)
+pages a human. A FAIL round never changes task status; only an all-pass round
+moves it (to IN_REVIEW, never further).
+
+## Review-time drift habits (gap findings)
+
+A problem discovered during acceptance/review that the contract does NOT
+cover is a **gap finding** — record it in the contract, never just fix it
+silently:
+
+1. **Append it on the spot.** Transcribe the human's finding as a criterion
+   via `lumo task criteria set <task> --file <desired-final-list> --human` —
+   the review-added semantics: the gap surfaced at review time, at the
+   current round.
+2. **Tag why the contract drifted** with `--cause
+<NEW_INFO|SCOPE_CHANGE|DRAFT_BLIND_SPOT|GRANULARITY|OTHER>`. Gap findings
+   are usually `DRAFT_BLIND_SPOT` (the draft missed it) or `NEW_INFO`
+   (information that didn't exist at drafting time).
+3. **Then bounce.** The appended criterion shows up in `lumo task status`
+   nextActions and the next verify round picks it up automatically — no
+   side-channel to-do list.
+
+How to read drift: information-lag and requirement-movement drift
+(`NEW_INFO`, `SCOPE_CHANGE`) is healthy — don't optimize it away.
+`DRAFT_BLIND_SPOT` clusters feed back into the drafting guide. **Zero drift
+across many tasks is a red flag, not a trophy** — it usually means contracts
+are too thin or state only sure-win clauses that can never be found wanting.
+
+## lumo task status — the read half (self-check entry point)
+
+`lumo task status [task] [--json]` is the read-only counterpart of the loop
+(LUM-344): pure read, milliseconds, no LLM, never writes — running it costs
+nothing and burns no round. Defaults to the session-bound task; an explicit
+identifier overrides.
+
+```
+lumo task status            # session-bound task
+lumo task status LUM-42     # explicit task
+lumo task status --json     # versioned machine-readable payload
+```
+
+### When to run it
+
+**Status-first recovery:** run it FIRST — before re-reading code or
+planning — whenever you:
+
+- resume a task in a new session (yours or another agent's earlier work);
+- come back after a verification round was rejected (`lumo verify` failed);
+- were told the task bounced in review (REVIEW_ADDED criteria may have been
+  appended at the round they surfaced — they show up here automatically).
+
+It answers "where does the loop stand": what already passed (don't redo it),
+what's unmet and why (the exact failure tails), and how many rounds are left.
+
+### What it prints
+
+- Header: task identifier/title/status + `verification round N/3` (round 0 =
+  never verified) + an escalation warning when the machine loop is exhausted.
+- **Criteria** — every criterion as `<glyph> <id>  [TYPE]  SOURCE@rN
+statement` (✓ latest verdict passed / ✗ failed / ○ no verdict yet) with its
+  checkpointer and latest verdict line (evidence pointer on pass, failure
+  tail on fail). `REVIEW_ADDED@rN` provenance is visible per row.
+- **History** — one line per recorded round: `rN · timestamp · X PASS / Y FAIL`.
+- **Last round failures** — the most recent round's FAIL verdicts with their
+  rejection reasons (why the last round bounced).
+- **Next actions** — the unmet criteria (latest verdict is not a pass:
+  failed or never verified, HUMAN ones included). This list IS the plan —
+  it is recomputed from the event log on every read, never maintained
+  separately. Empty + rounds recorded = awaiting human adjudication.
+
+### --json contract
+
+`--json` emits the full read model with a top-level `version` field
+(currently `1`). The schema is versioned: breaking shape changes bump the
+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.

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

@@ -51,7 +51,7 @@ async function docList(opts) {
     }
     else {
         const params = new URLSearchParams();
-        if (opts.scope && opts.scope !== 'all') {
+        if (opts.scope && opts.scope.toLowerCase() !== 'all') {
             const v = (0, doc_create_1.normalizeScope)(opts.scope);
             if (!v) {
                 console.error(`Error: invalid scope "${opts.scope}". Allowed: personal, workspace, all`);
@@ -74,7 +74,7 @@ async function docList(opts) {
     }
     const { documents } = (await res.json());
     let rows = documents;
-    if (opts.task && opts.scope && opts.scope !== 'all') {
+    if (opts.task && opts.scope && opts.scope.toLowerCase() !== 'all') {
         const v = (0, doc_create_1.normalizeScope)(opts.scope);
         if (v)
             rows = rows.filter(r => r.visibility === v);

package/dist/cli/src/index.js

@@ -256,7 +256,7 @@ task
 task
     .command('list')
     .description('List tasks assigned to you. Filter with --status, --project, --milestone, --limit.')
-    .option('-s, --status <value>', 'Filter by status: todo | in_progress | in_review | done')
+    .option('-s, --status <value>', 'Filter by status: todo | in_progress | in_review | done (case-insensitive)')
     .option('-p, --project <ref>', 'Filter by project name (case-insensitive)')
     .option('-n, --limit <count>', 'Show only the first N tasks')
     .option('-m, --milestone <ref>', 'Filter by milestone name or UUID (scopes to my tasks under that milestone)')
@@ -278,7 +278,7 @@ task
     .command('create <title>')
     .description('Create a task. --project required when workspace has >1 project; defaults: priority=low, assignee=me.')
     .option('-d, --description <text>', 'Task description')
-    .option('-p, --priority <level>', 'Priority: low | medium | high | urgent (default: low)')
+    .option('-p, --priority <level>', 'Priority: low | medium | high | urgent (case-insensitive; default: low)')
     .option('-a, --assignee <ref>', 'Assignee email, name, or "me" (default: me)')
     .option('--project <ref>', 'Project name or slug')
     .option('--milestone <ref>', 'Milestone name (case-insensitive)')
@@ -377,7 +377,7 @@ const taskMemory = task
 taskMemory
     .command('list [task]')
     .description("List a task's memories. <task> defaults to the session-bound task.")
-    .option('--category <cat>', 'Filter by trap|decision|convention|procedural')
+    .option('--category <cat>', 'Filter by trap|decision|convention|procedural (case-insensitive)')
     .option('-n, --limit <count>', 'Cap output to the first N rows')
     .action(wrap((taskArg, opts) => (0, memory_task_list_1.memoryTaskList)(taskArg, opts)));
 taskMemory
@@ -385,7 +385,7 @@ taskMemory
     .description('Record a memory on a task (<task> defaults to the bound session). ' +
     'Record only knowledge invisible in the codebase (the why, a runtime gotcha, a non-obvious failure, a non-trivial workflow); skip routine work. ' +
     'Pick --category then its fields.')
-    .requiredOption('--category <cat>', 'trap | decision | convention | procedural')
+    .requiredOption('--category <cat>', 'trap | decision | convention | procedural (case-insensitive)')
     .option('--trigger <text>', 'trap/procedural: the situation that triggers it')
     .option('--outcome <text>', 'trap: what goes wrong')
     .option('--workaround <text>', 'trap: optional fix')
@@ -397,7 +397,7 @@ taskMemory
     .option('--applies <text>', 'convention: where the rule applies')
     .option('--workflow <text>', 'procedural: the workflow name')
     .option('--step <text>', 'procedural: a step (repeatable)', collect, [])
-    .option('--agent <agent>', 'Producing agent: claude-code | codex | cursor | gemini-cli | github-copilot | windsurf (default claude-code)')
+    .option('--agent <agent>', 'Producing agent: claude-code | codex | cursor | gemini-cli | github-copilot | windsurf (case-insensitive; default claude-code)')
     .action(wrap((taskArg, opts) => (0, memory_task_add_1.memoryTaskAdd)(taskArg, opts)));
 const taskCriteria = task
     .command('criteria')
@@ -407,7 +407,7 @@ taskCriteria
     .description('Submit the whole acceptance contract from a JSON file. Default = initial agent draft (locked once submitted); --human records a HUMAN_EDIT revision (desired final list; items with "id" keep/update, missing ones are deleted).')
     .requiredOption('--file <path>', 'JSON array of criteria: [{"statement","verifierType":"MACHINE"|"HUMAN","checkpointer?","evidenceRequired?","id?"}]')
     .option('--human', 'Record a human contract revision (HUMAN_EDIT) transcribed from the conversation, with session provenance')
-    .option('--cause <tag>', 'Why the contract drifted (with --human): NEW_INFO | SCOPE_CHANGE | DRAFT_BLIND_SPOT | GRANULARITY | OTHER')
+    .option('--cause <tag>', 'Why the contract drifted (with --human): NEW_INFO | SCOPE_CHANGE | DRAFT_BLIND_SPOT | GRANULARITY | OTHER (case-insensitive)')
     .action(wrap((taskId, options) => (0, task_criteria_set_1.taskCriteriaSet)(taskId, options)));
 taskCriteria
     .command('list <task>')
@@ -423,7 +423,7 @@ taskArtifact
     .requiredOption('--title <title>', 'Artifact title')
     .requiredOption('--file <path>', 'File whose contents become the artifact body')
     .requiredOption('--source <source>', 'Spec-gen framework, formal name e.g. Superpowers | "Spec Kit" | BMad | OpenSpec | GSD (opaque; quote names with spaces)')
-    .requiredOption('--agent <agent>', 'Coding tool that produced the artifact: claude-code | codex | cursor | gemini-cli | github-copilot | windsurf')
+    .requiredOption('--agent <agent>', 'Coding tool that produced the artifact: claude-code | codex | cursor | gemini-cli | github-copilot | windsurf (case-insensitive)')
     .action(wrap((taskId, options) => (0, task_artifact_add_1.taskArtifactAdd)(taskId, options)));
 taskArtifact
     .command('update <task> <artifact-id>')
@@ -431,7 +431,7 @@ taskArtifact
     .option('--kind <kind>', 'New artifact kind (opaque)')
     .option('--title <title>', 'New artifact title')
     .option('--source <source>', 'New spec-gen framework, formal name e.g. Superpowers | "Spec Kit" | BMad | OpenSpec | GSD (quote names with spaces)')
-    .option('--agent <agent>', 'New coding tool: claude-code | codex | cursor | gemini-cli | github-copilot | windsurf')
+    .option('--agent <agent>', 'New coding tool: claude-code | codex | cursor | gemini-cli | github-copilot | windsurf (case-insensitive)')
     .action(wrap((taskId, artifactId, options) => (0, task_artifact_update_1.taskArtifactUpdate)(taskId, artifactId, options)));
 taskArtifact
     .command('list <task>')
@@ -459,13 +459,13 @@ const projectMemory = projectCmd
 projectMemory
     .command('list [project]')
     .description("List a project's PROJECT-scope memories. <project> defaults to the bound task's project.")
-    .option('--category <cat>', 'Filter by trap|decision|convention|procedural')
+    .option('--category <cat>', 'Filter by trap|decision|convention|procedural (case-insensitive)')
     .option('-n, --limit <count>', 'Cap output to the first N rows')
     .action(wrap((p, opts) => (0, memory_project_list_1.memoryProjectList)(p, opts)));
 projectMemory
     .command('add [project]')
     .description("Record a PROJECT-scope memory. Use PROJECT scope only when the lesson helps any task in the project. <project> defaults to the bound task's project.")
-    .requiredOption('--category <cat>', 'trap | decision | convention | procedural')
+    .requiredOption('--category <cat>', 'trap | decision | convention | procedural (case-insensitive)')
     .option('--trigger <text>', 'trap/procedural trigger')
     .option('--outcome <text>', 'trap outcome')
     .option('--workaround <text>', 'trap optional workaround')
@@ -477,7 +477,7 @@ projectMemory
     .option('--applies <text>', 'convention: where it applies')
     .option('--workflow <text>', 'procedural workflow')
     .option('--step <text>', 'procedural step (repeatable)', collect, [])
-    .option('--agent <agent>', 'Producing agent: claude-code | codex | cursor | gemini-cli | github-copilot | windsurf (default claude-code)')
+    .option('--agent <agent>', 'Producing agent: claude-code | codex | cursor | gemini-cli | github-copilot | windsurf (case-insensitive; default claude-code)')
     .action(wrap((p, opts) => (0, memory_project_add_1.memoryProjectAdd)(p, opts)));
 const memoryCmd = program
     .command('memory')
@@ -521,7 +521,7 @@ milestoneCmd
     .option('--project <ref>', 'Project name or slug (when identifier is a name)')
     .option('-n, --name <text>', 'New name')
     .option('-d, --description <text>', 'New description (empty string to clear)')
-    .option('-s, --status <value>', 'New status: planned | active | completed | cancelled')
+    .option('-s, --status <value>', 'New status: planned | active | completed | cancelled (case-insensitive)')
     .option('--start <date>', 'Start date YYYY-MM-DD (empty string to clear)')
     .option('--target <date>', 'Target date YYYY-MM-DD (empty string to clear)')
     .action(wrap((identifier, options) => (0, milestone_update_1.milestoneUpdate)(identifier, options)));
@@ -641,7 +641,7 @@ doc
     .description('Create a new document. Body comes from --content, --file, or piped stdin (pick one). --scope defaults to personal. Use --task LUM-N to bind the new doc to a task, --parent to file it under another doc.')
     .option('--content <text>', 'Inline markdown content')
     .option('--file <path>', 'Read markdown content from file')
-    .option('--scope <scope>', 'personal | workspace (default: personal)')
+    .option('--scope <scope>', 'personal | workspace (case-insensitive; default: personal)')
     .option('--project <ref>', 'Project name or slug to file under')
     .option('--task <LUM-N>', 'Bind to this task after creation')
     .option('--parent <doc>', 'File under this parent doc (cuid or title)')
@@ -651,7 +651,7 @@ doc
 doc
     .command('import-gdoc <url>')
     .description('Import a Google Doc as a Lumo doc (one-way Google → Lumo)')
-    .option('--scope <scope>', 'personal | workspace (default: personal)')
+    .option('--scope <scope>', 'personal | workspace (case-insensitive; default: personal)')
     .option('--task <LUM-N>', 'Bind the imported doc to this task')
     .action(wrap((url, opts) => (0, doc_import_gdoc_1.docImportGdoc)(url, opts)));
 doc
@@ -664,7 +664,7 @@ doc
     .option('--title <text>', 'New title')
     .option('--content <text>', 'Replace content (inline)')
     .option('--file <path>', 'Replace content from file')
-    .option('--scope <scope>', 'personal | workspace')
+    .option('--scope <scope>', 'personal | workspace (case-insensitive)')
     .option('--project <ref>', 'Project name/slug; pass "" to clear')
     .option('--tag <name>', 'Set tags by name (bulk replace, repeatable)', collect, [])
     .option('--tag-id <cuid>', 'Set tags by id (bulk replace, repeatable)', collect, [])
@@ -704,7 +704,7 @@ doc
 doc
     .command('list')
     .description('List documents visible to the current user')
-    .option('--scope <scope>', 'personal | workspace | all (default: all)')
+    .option('--scope <scope>', 'personal | workspace | all (case-insensitive; default: all)')
     .option('--project <ref>', 'Filter by project name/slug')
     .option('--task <LUM-N>', 'Only docs bound to this task')
     .option('--limit <n>', 'Cap output to first N rows')
@@ -732,7 +732,7 @@ doc
 doc
     .command('share <doc> <member>')
     .description('Share a document with a workspace member. PRIVATE docs are auto-promoted to SHARED. <member> accepts "me", an email, or a display name.')
-    .option('--role <role>', 'viewer | editor | manager (default: viewer)')
+    .option('--role <role>', 'viewer | editor | manager (case-insensitive; default: viewer)')
     .action(wrap((docRef, member, opts) => (0, doc_share_1.docShare)(docRef, member, opts)));
 doc
     .command('unshare <doc> <member>')
@@ -747,8 +747,8 @@ task
     .description('Update a task. Provide at least one of --title, --description, --status, --priority, --assignee, --milestone, --sprint, or tag flags. Use "" to clear description, assignee, milestone, or sprint binding. --tag/--tag-id (bulk replace) cannot be combined with --add-tag/--add-tag-id/--remove-tag/--remove-tag-id.')
     .option('-t, --title <text>', 'New title')
     .option('-d, --description <text>', 'New description (empty string to clear)')
-    .option('-s, --status <value>', 'New status: todo | in_progress | in_review | done')
-    .option('-p, --priority <level>', 'New priority: low | medium | high | urgent')
+    .option('-s, --status <value>', 'New status: todo | in_progress | in_review | done (case-insensitive)')
+    .option('-p, --priority <level>', 'New priority: low | medium | high | urgent (case-insensitive)')
     .option('-a, --assignee <ref>', 'New assignee: email, name, or "me" (empty string to clear)')
     .option('--milestone <ref>', 'Milestone name (case-insensitive); empty string to unbind')
     .option('--sprint <ref>', 'Sprint number or UUID to bind the task to; empty string to unbind from current sprint')

package/package.json

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