@lumoai/cli 1.26.0 → 1.28.0

package/assets/skill/SKILL.md

@@ -19,20 +19,20 @@ which lumo && lumo whoami
 
 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)               |
+| 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)               |
+| `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
 
@@ -98,6 +98,8 @@ The command catalog below is a **map**: it lists every command grouped by domain
 **Documents** — see [docs.md](references/docs.md)
 
 - `lumo doc create/update/show/list/delete` — document CRUD
+- `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 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
@@ -149,10 +151,10 @@ 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 3–7 outcome-level criteria 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
+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 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.
+**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/criteria.md

@@ -17,8 +17,10 @@ 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** (soft range — the server warns outside it but never
-   rejects; if you genuinely need more, merge related checks instead).
+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.
@@ -27,6 +29,23 @@ 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
@@ -129,8 +148,10 @@ before a `--human` revision. Empty contract prints a drafting pointer.
   binding.
 - **`lumo task context`**: the `## Acceptance criteria (contract)` section appears after the
   task description, before memory.
-- Review-time gap findings (`REVIEW_ADDED`, appended at the round they
-  surface) arrive via the verification loop, not via `criteria set`.
+- 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
 

package/assets/skill/references/docs.md

@@ -85,17 +85,50 @@ lumo doc update RFC --tag final --add-tag oops
 - User wants to revise an existing doc.
 - After running `lumo doc list` or `doc show`, if the user wants to change a doc's scope, title, or content.
 
-### `lumo doc show <doc>` — print one document's detail
+### `lumo doc show <doc> [--raw]` — print one document's detail
 
-Prints a key:value header (id, title, scope, project, created/updated timestamps, mentioned tasks) and the content rendered back to markdown.
+Default mode prints a key:value header (id, title, scope, project, created/updated timestamps, mentioned tasks) and the content rendered back to markdown.
 
 ```bash
 lumo doc show "RFC: doc CLI"
+lumo doc show cmd_xxx --raw > base.md   # byte-identical edit base
 ```
 
-Note: the markdown rendered by `doc show` is best-effort. Round-trip via `doc show > tmp.md && doc update --file tmp.md` is NOT guaranteed to be a no-op.
+**`--raw` (LUM-408)** prints the byte-identical markdown source of the last markdown upload — no header, no trailing newline added. The server stores the raw markdown (`sourceMarkdown`) alongside the rendered HTML on every markdown write (`doc create/update --content/--file/stdin`, gdoc import/sync), so `--raw` output IS a legal edit base: `doc show --raw > base.md`, edit, `doc update --file base.md` round-trips losslessly.
 
-Use when the user wants the current state or content of a doc without loading full task context.
+- A web-editor (HTML-direct) edit or revision restore **invalidates** the stored source — the doc's markdown source is gone until the next markdown upload.
+- When no source is stored (legacy doc or after an HTML edit), `--raw` **fails with exit 1 and a rebuild hint** — it never silently falls back to the lossy HTML→markdown reverse render (that fallback flattened tables: LUM-349). Rebuild flow: `doc show` (rendered) → reconstruct the markdown faithfully → `doc update --file rebuilt.md` → `--raw` works from then on.
+- Raw output is verbatim (unsanitized) by design — redirect it to a file rather than reading it in a terminal when the doc's provenance is uncertain.
+
+Note: the markdown rendered by **default-mode** `doc show` is still best-effort (tables flatten). Round-trip via `doc show > tmp.md && doc update --file tmp.md` is NOT a no-op — use `--raw` as the edit base instead.
+
+Use default mode when the user wants to read a doc; use `--raw` whenever the output will be edited and uploaded back.
+
+### When to suggest `doc show --raw`
+
+- Before any `doc update --file` that starts from existing remote content — fetch the base with `--raw`, never from rendered `doc show` output.
+- User asks "what's the exact source of this doc", or an agent needs a faithful local copy of a live doc.
+- If `--raw` errors (no stored source), walk the rebuild flow above instead of editing the rendered output.
+
+### `lumo doc diff <doc> --file <local.md>` — compare remote markdown source vs a local file
+
+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                                                                              |
+| --------------- | ------ | ---------------------------------------------------------------------------------- |
+| `--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).
+
+```bash
+lumo doc diff cmd_xxx --file docs/live-docs/research-intake-ledger.md
+```
+
+### When to suggest `doc diff`
+
+- Before uploading a locally edited file with `doc update --file` — check whether the remote source moved since the local copy was taken (prevents stale-upload clobbering, the #460 incident class).
+- When a repo-tracked markdown source (e.g. `docs/live-docs/`) and the live doc may have drifted and the user asks which is current.
+- After a suspected concurrent edit: a clean diff (exit 0) proves remote and local are in sync.
 
 ### `lumo doc list [flags]` — list documents
 
@@ -298,7 +331,7 @@ Synced cmd_xxx "Quarterly Plan" from Google
 The CLI does **not** currently support:
 
 - `--from-editor` (interactive $EDITOR).
-- Lossless markdown round-trip.
+- Lossless markdown round-trip from **rendered** `doc show` output (use `doc show --raw` — lossless whenever a markdown source is stored).
 - Reordering siblings within the same parent (`--before` / `--after`); use the Web UI for that.
 
 ### When to suggest session binding for docs

package/assets/skill/references/memory.md

@@ -45,17 +45,29 @@ the bound task; `lumo project memory add ...` records onto its project.
 
 The command prints **one** of these outcome lines:
 
-| Output line | Meaning |
-|---|---|
-| `Added <CATEGORY> <SCOPE> memory …` | No near-duplicate found; stored as a new row. |
-| `Merged into existing memory <id> (near-duplicate) …` | Near-duplicate found; the existing row was refined/updated in-place (UPDATE). |
-| `Superseded an existing memory; new version <id> …` | New content contradicts an old memory; old row invalidated, new row created (SUPERSEDE). |
-| `Skipped — duplicate of existing memory <id>, nothing written …` | Exact or near-exact duplicate; no write performed (NOOP). |
+| Output line                                                      | Meaning                                                                                  |
+| ---------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
+| `Added <CATEGORY> <SCOPE> memory …`                              | No near-duplicate found; stored as a new row.                                            |
+| `Merged into existing memory <id> (near-duplicate) …`            | Near-duplicate found; the existing row was refined/updated in-place (UPDATE).            |
+| `Superseded an existing memory; new version <id> …`              | New content contradicts an old memory; old row invalidated, new row created (SUPERSEDE). |
+| `Skipped — duplicate of existing memory <id>, nothing written …` | Exact or near-exact duplicate; no write performed (NOOP).                                |
 
 Content is **always normalized to English** before storing — the memory store has
 a single canonical language. If you supply text in another language the CLI
 translates it automatically; the stored memory will be in English.
 
+### Lumo memory vs the harness memory tool
+
+Claude Code / the Claude API may expose a file-based **memory tool** (a
+`/memories` directory the model writes autonomously). That store is the agent's
+private scratchpad — un-grounded, free-form, invisible to the team, and outside
+Lumo's flywheel. **Project engineering lessons always go through `lumo task/project
+memory add`** — never record them only in the harness memory tool, and never bulk-copy
+harness memory files into Lumo memory (they are ungrounded drafts; Lumo's
+extract→ground→reconcile write path is the only vetted entry). The two stores are
+layered, not mirrored: transient working notes may live in the harness tool,
+durable team knowledge lives in Lumo memory.
+
 ### When to record a memory (worthiness)
 
 Record only knowledge that is **invisible in the codebase** — the _why_ behind a

package/assets/skill/references/sessions.md

@@ -10,15 +10,18 @@ infer the task from local git so it can **suggest** one — it never binds for y
 
 - It reads the **current branch name** first (e.g. `lumo/LUM-145-...`), then the
   **most recent commit subjects** (e.g. `... [LUM-145]`), extracting the first
-  `LUM-<n>`.
+  task identifier. Detection is **prefix-agnostic** (LUM-419): any team prefix
+  matches — `SPEC-12` as much as `LUM-145` — using the same pattern the server
+  uses to link PR branches to tasks. Well-known acronym-number tokens
+  (`UTF-8`, `SHA-256`, `ISO-8601`, …) are skipped, never suggested.
 - On a hit it prints a single suggestion line and stops — the session stays
   **unbound** and no context is injected yet:
   `Detected LUM-145 (from branch name). Run lumo session attach LUM-145 to bind.`
   (the basis reads `from recent commits` when the hit came from commit subjects instead of the branch name)
   No task title is shown here because nothing was fetched; the title, memory,
   and PR-review todos appear only once you actually attach.
-- No match (detached HEAD, a non-lumo branch with no tagged commits, not a git
-  repo) → it degrades to the normal unbound prompt.
+- No match (detached HEAD, a branch with no identifier and no tagged commits,
+  not a git repo) → it degrades to the normal unbound prompt.
 
 **Agent guidance:** when you see a suggestion line, confirm the inferred task is
 the one the user wants, then run `lumo session attach <LUM-N>` (followed by

package/assets/skill/references/verify.md

@@ -71,6 +71,30 @@ 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
@@ -102,7 +126,7 @@ what's unmet and why (the exact failure tails), and how many rounds are left.
 - 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
+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`.

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

@@ -0,0 +1,82 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.docDiff = docDiff;
+const config_1 = require("../lib/config");
+const api_1 = require("../lib/api");
+const resolve_doc_id_1 = require("../lib/resolve-doc-id");
+const sanitize_1 = require("../lib/sanitize");
+const doc_input_1 = require("../lib/doc-input");
+const path_guard_1 = require("../lib/path-guard");
+const unified_diff_1 = require("../lib/unified-diff");
+/**
+ * `lumo doc diff <doc> --file <local.md>` (LUM-408).
+ *
+ * Compares the server-side markdown source (Document.sourceMarkdown — the
+ * byte-identical last markdown upload) against a local file, so a
+ * remote/local split-brain is visible on demand instead of discovered from
+ * memory after a stale upload clobbers someone's edit.
+ *
+ * Exit codes: 0 = sources byte-identical, 1 = divergent (or error).
+ */
+async function docDiff(reference, opts) {
+    if (!reference) {
+        console.error('Error: missing <doc>. Usage: lumo doc diff <doc> --file <local.md>');
+        return 1;
+    }
+    if (!opts.file) {
+        console.error('Error: --file <local.md> is required for doc diff');
+        return 1;
+    }
+    const creds = (0, config_1.readCredentials)();
+    if (!creds) {
+        console.error('Error: not logged in. Run `lumo auth login` first.');
+        return 1;
+    }
+    const apiUrl = (0, api_1.resolveAuthedApiUrl)(creds.apiUrl);
+    // Same sandbox as doc create/update --file: project-local, non-sensitive.
+    const check = (0, path_guard_1.checkArtifactFilePath)(opts.file);
+    if (!check.ok) {
+        console.error(check.reason === 'unreadable'
+            ? `Error: ${(0, doc_input_1.unreadableFileMessage)(opts.file)}`
+            : `Error: refusing to read ${opts.file} — ${check.detail}. ` +
+                `--file must be a non-sensitive path inside the project directory.`);
+        return 1;
+    }
+    const localText = await (0, doc_input_1.readFileUtf8)(check.resolved);
+    const id = await (0, resolve_doc_id_1.lookupDocId)(apiUrl, creds.token, reference);
+    if (!id) {
+        console.error(`Error: Document not found: ${reference}`);
+        return 1;
+    }
+    const res = await fetch(`${(0, api_1.trimTrailingSlash)(apiUrl)}/api/documents/${id}`, {
+        headers: { Authorization: `Bearer ${creds.token}` },
+    });
+    if (!res.ok) {
+        const text = await res.text();
+        console.error(`Error: ${res.status} ${res.statusText}: ${(0, sanitize_1.sanitizeField)(text)}`);
+        return 1;
+    }
+    const data = (await res.json());
+    const d = data.document;
+    if (!d) {
+        console.error('Error: server returned an empty document response');
+        return 1;
+    }
+    if (typeof d.sourceMarkdown !== 'string') {
+        console.error(`Error: ${d.id} has no stored markdown source to diff against (last edit ` +
+            `was HTML-direct or predates markdown source storage). Upload a markdown ` +
+            `base once (\`lumo doc update ${d.id} --file <base.md>\`) and diff from then on.`);
+        return 1;
+    }
+    if (d.sourceMarkdown === localText) {
+        console.log(`Clean: remote markdown source of ${d.id} matches ${opts.file} (${Buffer.byteLength(localText, 'utf8')} bytes)`);
+        return;
+    }
+    const diff = (0, unified_diff_1.formatUnifiedDiff)(d.sourceMarkdown, localText, `remote/${d.id} (sourceMarkdown)`, `local/${opts.file}`);
+    // Byte-level divergence with identical line sequences (e.g. trailing
+    // newline only) still counts as divergent — say so explicitly.
+    console.log(diff !== ''
+        ? (0, sanitize_1.sanitizeField)(diff)
+        : `Divergent: byte-level difference only (e.g. trailing newline) between remote ${d.id} and ${opts.file}`);
+    return 1;
+}

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

@@ -27,9 +27,9 @@ function formatShowOutput(vm) {
     const header = lines.join('\n');
     return vm.bodyMarkdown ? `${header}\n\n${(0, sanitize_1.sanitizeField)(vm.bodyMarkdown)}` : header;
 }
-async function docShow(reference) {
+async function docShow(reference, opts = {}) {
     if (!reference) {
-        console.error('Error: missing <doc>. Usage: lumo doc show <doc>');
+        console.error('Error: missing <doc>. Usage: lumo doc show <doc> [--raw]');
         return 1;
     }
     const creds = (0, config_1.readCredentials)();
@@ -58,6 +58,23 @@ async function docShow(reference) {
         console.error('Error: server returned an empty document response');
         return 1;
     }
+    if (opts.raw) {
+        // Byte-identical markdown source of the last markdown upload (LUM-408).
+        // Written verbatim (no header, no sanitization, no added newline) so the
+        // output is a legal edit base: `doc show --raw > base.md` round-trips.
+        // No silent fallback to the lossy HTML→markdown reverse render — that
+        // fallback is exactly what flattened tables in LUM-349.
+        if (typeof d.sourceMarkdown !== 'string') {
+            console.error(`Error: ${d.id} has no stored markdown source (last edit was HTML-direct ` +
+                `or predates markdown source storage). --raw refuses to fall back to the ` +
+                `lossy HTML→markdown render. Rebuild a base instead: run \`lumo doc show ${d.id}\`, ` +
+                `reconstruct the markdown faithfully, then \`lumo doc update ${d.id} --file <rebuilt.md>\` ` +
+                `— from then on --raw works.`);
+            return 1;
+        }
+        process.stdout.write(d.sourceMarkdown);
+        return;
+    }
     // Server returns `contentMarkdown` derived from the HTML body (LUM-83+).
     // Fall back to parsing the raw content as legacy Tiptap JSON for docs
     // written before the storage shape changed.

package/dist/cli/src/index.js

@@ -34,6 +34,7 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.program = void 0;
 const fs = __importStar(require("fs"));
 const os = __importStar(require("os"));
 const path = __importStar(require("path"));
@@ -107,6 +108,7 @@ const doc_import_gdoc_1 = require("./commands/doc-import-gdoc");
 const doc_sync_1 = require("./commands/doc-sync");
 const doc_update_1 = require("./commands/doc-update");
 const doc_show_1 = require("./commands/doc-show");
+const doc_diff_1 = require("./commands/doc-diff");
 const doc_list_1 = require("./commands/doc-list");
 const doc_delete_1 = require("./commands/doc-delete");
 const doc_bind_1 = require("./commands/doc-bind");
@@ -122,9 +124,16 @@ const worktree_rm_1 = require("./commands/worktree-rm");
 const worktree_list_1 = require("./commands/worktree-list");
 const update_check_1 = require("./lib/update-check");
 const sanitize_1 = require("./lib/sanitize");
+// Introspection mode: tooling (scripts/analysis grammar extraction) imports
+// this module to walk the registered commander tree without running the CLI.
+// Skips package.json resolution (which assumes the compiled dist/ layout),
+// update checks, local-state cleanup, and parseAsync. Never set for real runs.
+const isIntrospect = process.env.LUMO_CLI_INTROSPECT === '1';
 // Resolve package.json relative to __dirname so this works regardless of how
 // deep the compiled output ends up (flat dist/ or nested dist/cli/src/).
-const pkg = require(path.resolve(__dirname, '../../..', 'package.json'));
+const pkg = isIntrospect
+    ? { name: '@lumoai/cli', version: '0.0.0-introspect' }
+    : require(path.resolve(__dirname, '../../..', 'package.json'));
 // Detached background-refresh worker: re-entry point for the spawn() in
 // maybeRefreshInBackground(). Fetches latest, writes cache, exits — skipping
 // commander.parseAsync() below.
@@ -134,7 +143,7 @@ if (isUpdateCheckWorker) {
         .catch(() => { })
         .finally(() => process.exit(0));
 }
-else {
+else if (!isIntrospect) {
     (0, update_check_1.printUpdateNoticeIfAny)(pkg.name, pkg.version);
     (0, update_check_1.maybeRefreshInBackground)(pkg.name);
 }
@@ -142,8 +151,7 @@ else {
 // is now server-authoritative; the legacy global pointer and the
 // per-session sentinel directory are both obsolete. Failures are
 // swallowed so a permission glitch doesn't prevent CLI invocation.
-;
-(() => {
+if (!isIntrospect) {
     const dir = process.env.LUMO_CONFIG_DIR || path.join(os.homedir(), '.lumo');
     try {
         fs.rmSync(path.join(dir, 'current-task.json'), { force: true });
@@ -153,7 +161,7 @@ else {
         fs.rmSync(path.join(dir, 'sessions'), { recursive: true, force: true });
     }
     catch { }
-})();
+}
 const collect = (val, acc) => [...acc, val];
 function wrap(fn) {
     return async (...args) => {
@@ -178,6 +186,7 @@ const program = new commander_1.Command()
     // created via .command() inherit these settings.
     .showSuggestionAfterError(true)
     .showHelpAfterError('(run the command with --help to list its valid flags and arguments)');
+exports.program = program;
 const auth = program.command('auth').description('Manage Lumo authentication');
 auth
     .command('login')
@@ -665,8 +674,14 @@ doc
     .action(wrap((reference, opts) => (0, doc_update_1.docUpdate)(reference, opts)));
 doc
     .command('show <doc>')
-    .description('Show document header and body (doc = title or cuid)')
-    .action(wrap(reference => (0, doc_show_1.docShow)(reference)));
+    .description('Show document header and body (doc = title or cuid). --raw prints the byte-identical markdown source of the last markdown upload (a legal edit base); it errors when no markdown source is stored instead of falling back to the lossy HTML→markdown render.')
+    .option('--raw', 'Print the stored markdown source verbatim (no header); errors if absent')
+    .action(wrap((reference, opts) => (0, doc_show_1.docShow)(reference, opts)));
+doc
+    .command('diff <doc>')
+    .description('Compare the server-side markdown source against a local file. Exit 0 when byte-identical, 1 with a unified diff when divergent. Requires the doc to have a stored markdown source.')
+    .requiredOption('--file <path>', 'Local markdown file to compare against')
+    .action(wrap((reference, opts) => (0, doc_diff_1.docDiff)(reference, opts)));
 doc
     .command('list')
     .description('List documents visible to the current user')
@@ -876,7 +891,7 @@ for (const [slug, description] of HOOK_SUBCOMMANDS) {
         .option('--agent <token>', 'Coding agent that owns this session (e.g. claude-code, codex). Baked in by `lumo setup --agent`.')
         .action(wrap((opts) => (0, hook_1.hookCommand)(slug, opts.agent)));
 }
-if (!isUpdateCheckWorker) {
+if (!isUpdateCheckWorker && !isIntrospect) {
     program.parseAsync(process.argv).catch(err => {
         const msg = err instanceof Error ? err.message : String(err);
         console.error(`Error: ${(0, sanitize_1.sanitizeField)(msg)}`);

package/dist/cli/src/lib/git-task.js

@@ -1,24 +1,15 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.matchTaskIdentifier = matchTaskIdentifier;
+exports.matchTaskIdentifier = void 0;
 exports.extractTaskFromGit = extractTaskFromGit;
 const child_process_1 = require("child_process");
+const task_identifier_1 = require("../../../shared/src/task-identifier");
+Object.defineProperty(exports, "matchTaskIdentifier", { enumerable: true, get: function () { return task_identifier_1.matchTaskIdentifier; } });
 /**
  * How many recent commit subjects to scan when the branch name carries no
  * task id (e.g. on a generic feature branch or detached HEAD).
  */
 const DEFAULT_COMMIT_DEPTH = 20;
-const TASK_RE = /LUM-(\d+)/i;
-/**
- * Pull the first `LUM-<n>` token out of arbitrary text (a branch name or a
- * commit subject) and normalize it to upper case. Returns null when no task
- * id is present. The leading `-` in the pattern means the bare word `lumo`
- * never matches.
- */
-function matchTaskIdentifier(text) {
-    const m = text.match(TASK_RE);
-    return m ? `LUM-${m[1]}` : null;
-}
 /**
  * Run a git subcommand and return trimmed stdout, or '' on any failure
  * (non-zero exit, spawn error, not a repository, timeout). Never throws.
@@ -41,17 +32,18 @@ function gitOutput(args, cwd) {
 /**
  * Infer the task to work on from local git: prefer the current branch name
  * (e.g. `lumo/LUM-145-...`), then fall back to the most recent commit
- * subjects (e.g. `... [LUM-145]`). Returns null when nothing matches —
- * detached HEAD (branch reads `HEAD`), a non-lumo branch with no tagged
- * commits, or a directory that is not a git repository all degrade to null.
+ * subjects (e.g. `... [LUM-145]`). Any team prefix matches (SPEC-12 as much
+ * as LUM-145). Returns null when nothing matches — detached HEAD (branch
+ * reads `HEAD`), a branch with no identifier and no tagged commits, or a
+ * directory that is not a git repository all degrade to null.
  */
 function extractTaskFromGit(cwd, commitDepth = DEFAULT_COMMIT_DEPTH) {
     const branch = gitOutput(['rev-parse', '--abbrev-ref', 'HEAD'], cwd);
-    const fromBranch = matchTaskIdentifier(branch);
+    const fromBranch = (0, task_identifier_1.matchTaskIdentifier)(branch);
     if (fromBranch)
         return { identifier: fromBranch, source: 'branch' };
     const log = gitOutput(['log', '-n', String(commitDepth), '--format=%s'], cwd);
-    const fromLog = matchTaskIdentifier(log);
+    const fromLog = (0, task_identifier_1.matchTaskIdentifier)(log);
     if (fromLog)
         return { identifier: fromLog, source: 'commit' };
     return null;

package/dist/cli/src/lib/unified-diff.js

@@ -0,0 +1,154 @@
+"use strict";
+/**
+ * Minimal line-based unified diff (LUM-408, `lumo doc diff`).
+ *
+ * Pure and dependency-free: the CLI ships only commander + markdown-it, and
+ * shelling out to system `diff` would not be portable. Equality (the exit
+ * code) is decided on raw bytes by the caller — this renderer only has to
+ * make the divergence readable, so a plain LCS with a size guard is enough.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.formatUnifiedDiff = formatUnifiedDiff;
+const CONTEXT_LINES = 3;
+/** Above this old×new line product the LCS table is too big — degrade to a single whole-block hunk. */
+const MAX_LCS_CELLS = 4_000_000;
+function splitLines(text) {
+    return text.split('\n');
+}
+/** LCS-based op list for the (already prefix/suffix-trimmed) middle section. */
+function diffOps(oldLines, newLines) {
+    const n = oldLines.length;
+    const m = newLines.length;
+    if (n * m > MAX_LCS_CELLS) {
+        return [
+            ...oldLines.map(text => ({ type: 'del', text })),
+            ...newLines.map(text => ({ type: 'add', text })),
+        ];
+    }
+    // lcs[i][j] = LCS length of oldLines[i:] vs newLines[j:]
+    const lcs = Array.from({ length: n + 1 }, () => new Array(m + 1).fill(0));
+    for (let i = n - 1; i >= 0; i--) {
+        for (let j = m - 1; j >= 0; j--) {
+            lcs[i][j] =
+                oldLines[i] === newLines[j]
+                    ? lcs[i + 1][j + 1] + 1
+                    : Math.max(lcs[i + 1][j], lcs[i][j + 1]);
+        }
+    }
+    const ops = [];
+    let i = 0;
+    let j = 0;
+    while (i < n && j < m) {
+        if (oldLines[i] === newLines[j]) {
+            ops.push({ type: 'ctx', text: oldLines[i] });
+            i++;
+            j++;
+        }
+        else if (lcs[i + 1][j] >= lcs[i][j + 1]) {
+            ops.push({ type: 'del', text: oldLines[i] });
+            i++;
+        }
+        else {
+            ops.push({ type: 'add', text: newLines[j] });
+            j++;
+        }
+    }
+    while (i < n)
+        ops.push({ type: 'del', text: oldLines[i++] });
+    while (j < m)
+        ops.push({ type: 'add', text: newLines[j++] });
+    return ops;
+}
+/**
+ * Render a unified diff between two texts. Returns '' when the line
+ * sequences are identical (callers decide byte-equality separately —
+ * e.g. a trailing-newline-only difference still flips the exit code).
+ */
+function formatUnifiedDiff(oldText, newText, oldLabel, newLabel) {
+    const oldAll = splitLines(oldText);
+    const newAll = splitLines(newText);
+    // Trim the common prefix/suffix so the LCS only sees the changed middle.
+    let prefix = 0;
+    while (prefix < oldAll.length &&
+        prefix < newAll.length &&
+        oldAll[prefix] === newAll[prefix]) {
+        prefix++;
+    }
+    let suffix = 0;
+    while (suffix < oldAll.length - prefix &&
+        suffix < newAll.length - prefix &&
+        oldAll[oldAll.length - 1 - suffix] === newAll[newAll.length - 1 - suffix]) {
+        suffix++;
+    }
+    const middleOps = diffOps(oldAll.slice(prefix, oldAll.length - suffix), newAll.slice(prefix, newAll.length - suffix));
+    if (!middleOps.some(op => op.type !== 'ctx'))
+        return '';
+    // Re-attach trimmed context so hunks can carry CONTEXT_LINES around edits.
+    const ops = [
+        ...oldAll.slice(0, prefix).map(text => ({ type: 'ctx', text })),
+        ...middleOps,
+        ...oldAll
+            .slice(oldAll.length - suffix)
+            .map(text => ({ type: 'ctx', text })),
+    ];
+    // Group ops into hunks: a change plus up to CONTEXT_LINES of context on
+    // each side; nearby changes merge into one hunk.
+    const lines = [`--- ${oldLabel}`, `+++ ${newLabel}`];
+    let oldLineNo = 1;
+    let newLineNo = 1;
+    let idx = 0;
+    while (idx < ops.length) {
+        if (ops[idx].type === 'ctx') {
+            oldLineNo++;
+            newLineNo++;
+            idx++;
+            continue;
+        }
+        // Found a change — open a hunk starting CONTEXT_LINES back.
+        let hunkStart = idx;
+        let ctxBack = 0;
+        while (hunkStart > 0 && ops[hunkStart - 1].type === 'ctx' && ctxBack < CONTEXT_LINES) {
+            hunkStart--;
+            ctxBack++;
+        }
+        // Extend forward: include changes separated by ≤ 2×CONTEXT_LINES context.
+        let hunkEnd = idx;
+        let scan = idx;
+        while (scan < ops.length) {
+            if (ops[scan].type !== 'ctx') {
+                hunkEnd = scan;
+                scan++;
+                continue;
+            }
+            let run = 0;
+            while (scan + run < ops.length && ops[scan + run].type === 'ctx')
+                run++;
+            if (scan + run < ops.length && run <= CONTEXT_LINES * 2) {
+                scan += run;
+                continue;
+            }
+            break;
+        }
+        const tail = Math.min(hunkEnd + CONTEXT_LINES, ops.length - 1);
+        const hunkOps = ops.slice(hunkStart, tail + 1);
+        const oldStart = oldLineNo - ctxBack;
+        const newStart = newLineNo - ctxBack;
+        const oldCount = hunkOps.filter(o => o.type !== 'add').length;
+        const newCount = hunkOps.filter(o => o.type !== 'del').length;
+        lines.push(`@@ -${oldStart}${oldCount === 1 ? '' : `,${oldCount}`} +${newStart}${newCount === 1 ? '' : `,${newCount}`} @@`);
+        for (const op of hunkOps) {
+            const marker = op.type === 'ctx' ? ' ' : op.type === 'del' ? '-' : '+';
+            lines.push(`${marker}${op.text}`);
+        }
+        // Advance the line counters across everything the hunk consumed.
+        for (let k = idx; k <= tail; k++) {
+            const t = ops[k].type;
+            if (t !== 'add')
+                oldLineNo++;
+            if (t !== 'del')
+                newLineNo++;
+        }
+        idx = tail + 1;
+    }
+    return lines.join('\n');
+}

package/dist/shared/src/task-identifier.js

@@ -0,0 +1,51 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TASK_IDENTIFIER_PATTERN = void 0;
+exports.matchTaskIdentifier = matchTaskIdentifier;
+/**
+ * Single source of truth for the task-identifier pattern (LUM-419).
+ *
+ * Consumed by both sides so they cannot drift:
+ *   - server: lib/integrations/github/branch.ts (webhook branch → task linking)
+ *   - CLI:    cli/src/lib/git-task.ts (session-start git-suggest)
+ *
+ * A task identifier is `<TEAM>-<n>` where TEAM is the team's configured
+ * prefix (`Team.identifier`, 1–10 letters) — e.g. LUM-419, SPEC-123. The
+ * prefix is NOT hardcoded to any one team.
+ */
+exports.TASK_IDENTIFIER_PATTERN = String.raw `\b([A-Za-z]{1,10}-\d+)\b`;
+/**
+ * Acronym-number tokens that match the identifier shape but are never task
+ * ids. Commit subjects routinely contain these ("fix UTF-8 handling",
+ * "use SHA-256"), so the matcher skips them instead of suggesting a bogus
+ * session attach. Compared against the uppercased prefix segment.
+ */
+const NON_TASK_PREFIXES = new Set([
+    'AES',
+    'CVE',
+    'GPT',
+    'HTTP',
+    'ISO',
+    'RFC',
+    'RSA',
+    'SHA',
+    'TLS',
+    'UTF',
+]);
+/**
+ * Extract the first task identifier from arbitrary text (a branch name or a
+ * commit subject), normalized to upper case. Tokens whose prefix is a known
+ * non-task acronym (UTF-8, SHA-256, …) are skipped; later genuine matches in
+ * the same text still win. Returns null when nothing matches.
+ */
+function matchTaskIdentifier(text) {
+    const re = new RegExp(exports.TASK_IDENTIFIER_PATTERN, 'g');
+    for (const m of text.matchAll(re)) {
+        const identifier = m[1].toUpperCase();
+        const prefix = identifier.slice(0, identifier.lastIndexOf('-'));
+        if (NON_TASK_PREFIXES.has(prefix))
+            continue;
+        return identifier;
+    }
+    return null;
+}

package/package.json

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