@lumoai/cli 1.27.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
 
@@ -151,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/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/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"));
@@ -123,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.
@@ -135,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);
 }
@@ -143,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 });
@@ -154,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) => {
@@ -179,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')
@@ -883,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/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.27.0",
+  "version": "1.28.0",
   "description": "Lumo CLI — manage tasks and sessions from the terminal",
   "license": "MIT",
   "author": "cli@uselumo.ai",