@lumoai/cli 1.29.0 → 1.30.0

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/commands/doc-section-edit.js

@@ -69,6 +69,8 @@ async function docSectionEdit(mode, reference, opts) {
     }
     if (ifRevision !== undefined)
         body.ifRevision = ifRevision;
+    if (opts.allowShrink)
+        body.allowShrink = true;
     const res = await fetch(`${(0, api_1.trimTrailingSlash)(apiUrl)}/api/documents/${id}/section`, {
         method: 'POST',
         headers: {
@@ -79,18 +81,20 @@ async function docSectionEdit(mode, reference, opts) {
     });
     if (!res.ok) {
         const text = await res.text();
-        let message = text;
-        try {
-            message = JSON.parse(text).error ?? text;
-        }
-        catch {
-            // non-JSON error body — print as-is
-        }
+        const message = (0, api_1.extractErrorMessage)(text);
         if (res.status === 409) {
             console.error(`Error: revision conflict: ${(0, sanitize_1.sanitizeField)(message)}`);
             console.error(`Hint: re-read the section (lumo doc show ${reference}${opts.section ? ` --section "${opts.section}"` : ''}), rebase your edit on it, then retry with --if-revision <current>.`);
             return 1;
         }
+        if (res.status === 422) {
+            // Structure guard rejection (LUM-410): the replacement drops structure
+            // the addressed section has (the message names each category, old→new).
+            console.error(`Error: ${(0, sanitize_1.sanitizeField)(message)}`);
+            console.error(`Hint: if the deletion is intentional, re-run with --allow-shrink. ` +
+                `Otherwise re-read the section (lumo doc show ${reference}${opts.section ? ` --section "${opts.section}"` : ''}) and rebase your edit on it.`);
+            return 1;
+        }
         console.error(`Error: ${res.status} ${res.statusText}: ${(0, sanitize_1.sanitizeField)(message)}`);
         return 1;
     }

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

@@ -82,6 +82,8 @@ async function docUpdate(reference, opts) {
         }
         body.ifRevision = Number(opts.ifRevision);
     }
+    if (opts.allowShrink)
+        body.allowShrink = true;
     // Resolve tag refs into ids
     const deps = { apiUrl, token: creds.token };
     let tagIds;
@@ -114,8 +116,10 @@ async function docUpdate(reference, opts) {
         body.addTagIds = addTagIds;
     if (removeTagIds !== undefined)
         body.removeTagIds = removeTagIds;
-    // --if-revision is a precondition, not a field — alone it's not an update.
-    if (Object.keys(body).filter(k => k !== 'ifRevision').length === 0) {
+    // --if-revision / --allow-shrink are modifiers, not fields — alone they
+    // are not an update.
+    if (Object.keys(body).filter(k => k !== 'ifRevision' && k !== 'allowShrink')
+        .length === 0) {
         console.error('Error: no fields to update — provide at least one flag');
         return 1;
     }
@@ -130,19 +134,22 @@ async function docUpdate(reference, opts) {
     });
     if (!res.ok) {
         const text = await res.text();
+        const message = (0, api_1.extractErrorMessage)(text);
         if (res.status === 409 && opts.ifRevision !== undefined) {
-            let message = text;
-            try {
-                message = JSON.parse(text).error ?? text;
-            }
-            catch {
-                // non-JSON error body — print as-is
-            }
             console.error(`Error: revision conflict: ${(0, sanitize_1.sanitizeField)(message)}`);
             console.error(`Hint: re-read the doc (lumo doc show ${reference} --raw), rebase your edit ` +
                 `on the current source, then retry with --if-revision <current>.`);
             return 1;
         }
+        if (res.status === 422) {
+            // Structure guard rejection (LUM-410): the new body drops structure
+            // the stored body has (the message names each category, old→new).
+            console.error(`Error: ${(0, sanitize_1.sanitizeField)(message)}`);
+            console.error(`Hint: if the deletion is intentional, re-run with --allow-shrink. ` +
+                `Otherwise re-read the current source (lumo doc show ${reference} --raw) ` +
+                `and rebase your edit on it.`);
+            return 1;
+        }
         console.error(`Error: ${res.status} ${res.statusText}: ${(0, sanitize_1.sanitizeField)(text)}`);
         return 1;
     }

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
@@ -660,11 +660,11 @@ doc
     .action(wrap(ref => (0, doc_sync_1.docSync)(ref)));
 doc
     .command('update <doc>')
-    .description('Update an existing document. <doc> accepts a cuid or a case-insensitive title (ambiguous titles fail with candidates). Replacement body comes from --content, --file, or piped stdin (pick one). --tag/--tag-id (bulk replace) cannot be combined with --add-tag/--add-tag-id/--remove-tag/--remove-tag-id.')
+    .description('Update an existing document. <doc> accepts a cuid or a case-insensitive title (ambiguous titles fail with candidates). Replacement body comes from --content, --file, or piped stdin (pick one). A body update that drops tables/rows/headings versus the stored body is rejected with 422 (structure guard) unless --allow-shrink is passed. --tag/--tag-id (bulk replace) cannot be combined with --add-tag/--add-tag-id/--remove-tag/--remove-tag-id.')
     .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, [])
@@ -673,6 +673,7 @@ doc
     .option('--remove-tag <name>', 'Remove tag by name (repeatable). Unknown names are find-or-create, so prefer --remove-tag-id to avoid orphan rows.', collect, [])
     .option('--remove-tag-id <cuid>', 'Remove tag by id (repeatable). Unknown ids are a no-op.', collect, [])
     .option('--if-revision <n>', 'Only apply if the doc body is still at this revision (from doc show); mismatch fails with a 409 conflict')
+    .option('--allow-shrink', 'Let the update through even when it drops tables/rows/headings versus the stored body (default: rejected with 422)')
     .action(wrap((reference, opts) => (0, doc_update_1.docUpdate)(reference, opts)));
 doc
     .command('show <doc>')
@@ -682,11 +683,12 @@ doc
     .action(wrap((reference, opts) => (0, doc_show_1.docShow)(reference, opts)));
 doc
     .command('patch <doc>')
-    .description('Replace one heading-addressed section of the markdown source (heading line included), leaving every byte outside the section untouched. Requires the doc to have a stored markdown source. Commits conditionally on the body revision: a concurrent edit fails with 409 instead of being overwritten.')
+    .description('Replace one heading-addressed section of the markdown source (heading line included), leaving every byte outside the section untouched. Requires the doc to have a stored markdown source. Commits conditionally on the body revision: a concurrent edit fails with 409 instead of being overwritten. A replacement that drops tables/rows/headings within the addressed section is rejected with 422 (structure guard) unless --allow-shrink is passed.')
     .requiredOption('--section <heading>', 'Heading of the section to replace (prefix with #… to pin depth)')
     .option('--content <text>', 'New section content (inline markdown)')
     .option('--file <path>', 'New section content from file')
     .option('--if-revision <n>', 'Only apply if the doc body is still at this revision (from doc show)')
+    .option('--allow-shrink', 'Let the patch through even when it drops tables/rows/headings within the addressed section (default: rejected with 422)')
     .action(wrap((reference, opts) => (0, doc_section_edit_1.docPatch)(reference, opts)));
 doc
     .command('append <doc>')
@@ -704,7 +706,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 +734,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 +749,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/dist/cli/src/lib/api.js

@@ -5,6 +5,7 @@ exports.hostMismatchWarning = hostMismatchWarning;
 exports.resolveAuthedApiUrl = resolveAuthedApiUrl;
 exports.resolveApiUrl = resolveApiUrl;
 exports.trimTrailingSlash = trimTrailingSlash;
+exports.extractErrorMessage = extractErrorMessage;
 exports.verifyToken = verifyToken;
 const DEFAULT_API_URL = 'https://www.uselumo.ai';
 // Hostnames allowed to use plaintext http:// — local dev only. Everything
@@ -91,6 +92,18 @@ function resolveApiUrl() {
 function trimTrailingSlash(url) {
     return url.replace(/\/+$/, '');
 }
+/**
+ * Pull the `error` field out of a JSON API error body; non-JSON bodies (or
+ * JSON without an `error` string) fall back to the raw text unchanged.
+ */
+function extractErrorMessage(text) {
+    try {
+        return JSON.parse(text).error ?? text;
+    }
+    catch {
+        return text;
+    }
+}
 async function verifyToken(apiUrl, token) {
     let res;
     try {

package/dist/shared/src/html-structure.js

@@ -0,0 +1,79 @@
+"use strict";
+/**
+ * Structural tag counting over rendered document HTML.
+ *
+ * Single source of truth shared by the server-side structure guard on the
+ * document update path (LUM-410) and `scripts/verify-live-doc.ts`, so the
+ * guard and the script can never drift on what counts as "structure".
+ *
+ * Counting is regex-based over the rendered HTML. That is safe here because
+ * both inputs always come out of the same `markdownToHtml` renderer (or the
+ * Tiptap editor's serializer), which emits plain lowercase tags — this is
+ * not a general-purpose HTML parser.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TAG_PATTERNS = void 0;
+exports.countPattern = countPattern;
+exports.compareStructure = compareStructure;
+exports.hardMismatches = hardMismatches;
+exports.softMismatches = softMismatches;
+exports.structureShrinks = structureShrinks;
+exports.formatStructureShrinks = formatStructureShrinks;
+/** Categories `verify-live-doc.ts` reports on (hard = table structure). */
+exports.TAG_PATTERNS = [
+    { tag: 'table', pattern: /<table/g, hard: true },
+    { tag: 'tr', pattern: /<tr/g, hard: true },
+    { tag: 'h1', pattern: /<h1/g, hard: false },
+    { tag: 'h2', pattern: /<h2/g, hard: false },
+    { tag: 'h3', pattern: /<h3/g, hard: false },
+    { tag: 'li', pattern: /<li/g, hard: false },
+    { tag: 'a', pattern: /<a[\s>]/g, hard: false },
+    { tag: 'strong', pattern: /<strong/g, hard: false },
+    { tag: 'code', pattern: /<code/g, hard: false },
+    { tag: 'blockquote', pattern: /<blockquote/g, hard: false },
+];
+function countPattern(html, pattern) {
+    return (html.match(pattern) ?? []).length;
+}
+function compareStructure(renderedHtml, storedHtml) {
+    return exports.TAG_PATTERNS.map(({ tag, pattern, hard }) => ({
+        tag,
+        rendered: countPattern(renderedHtml, pattern),
+        stored: countPattern(storedHtml, pattern),
+        hard,
+    }));
+}
+function hardMismatches(checks) {
+    return checks.filter(c => c.hard && c.rendered !== c.stored);
+}
+function softMismatches(checks) {
+    return checks.filter(c => !c.hard && c.rendered !== c.stored);
+}
+/**
+ * Categories the update guard protects. Headings are counted as one
+ * aggregate bucket (h1–h6) so promoting/demoting a heading level is not a
+ * loss — only dropping a section heading outright is.
+ */
+const GUARD_PATTERNS = [
+    { tag: 'table', pattern: /<table/g },
+    { tag: 'tr', pattern: /<tr/g },
+    { tag: 'heading', pattern: /<h[1-6][\s>]/g },
+];
+/**
+ * Compare two rendered HTML bodies and report every guarded category whose
+ * count shrank. Empty result = the edit loses no guarded structure.
+ */
+function structureShrinks(oldHtml, newHtml) {
+    const shrinks = [];
+    for (const { tag, pattern } of GUARD_PATTERNS) {
+        const before = countPattern(oldHtml, pattern);
+        const after = countPattern(newHtml, pattern);
+        if (after < before)
+            shrinks.push({ tag, before, after });
+    }
+    return shrinks;
+}
+/** "table 3→0, tr 12→0" — the per-category loss detail for error messages. */
+function formatStructureShrinks(shrinks) {
+    return shrinks.map(s => `${s.tag} ${s.before}→${s.after}`).join(', ');
+}

package/package.json

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