@lumoai/cli 1.50.0 → 1.51.0

package/assets/skill/SKILL.md

@@ -126,6 +126,7 @@ lumo fidelity show LUM-42 --json
 - `lumo milestone add/remove <id> <task...>` — batch bind/unbind tasks
 - `lumo milestone summary [--retry]` — AI retro
 - `lumo milestone reorder/move` — manual ordering
+- `lumo milestone criteria set/list/verdict` — milestone-level **exit criteria** (LUM-643): the close contract, drafted & adjudicated (裁定) by the steward (LUM-640) or a human. Unresolved criteria (pending or NOT_MET) block `--status completed` **and** the LUM-624 auto-rollup with 409/fail-closed; human override is web-only (`?force=1`, stamped as a persistent trail). `verdict --met` on `EXTERNAL_FACT` requires `--evidence` (422); `PENDING_OUTCOME` can never be MET
 
 **Documents** — CRUD/sharing → [docs.md](references/docs.md); **editing live docs** (raw/section/patch/append/diff/rebuild) → [doc-editing.md](references/doc-editing.md)
 

package/assets/skill/references/milestones.md

@@ -98,25 +98,92 @@ lumo milestone show 11111111-2222-3333-4444-555555555555
 
 ### `lumo milestone update <identifier>` — patch a milestone
 
-| Flag                   | Type   | Notes                                                            |
-| ---------------------- | ------ | ---------------------------------------------------------------- |
-| `--project <ref>`      | string | Required when identifier is a name and workspace has >1 project. |
-| `-n, --name <text>`    | string | Cannot be empty.                                                 |
-| `-d, --description <>` | string | `--description ""` clears.                                       |
-| `-s, --status <value>` | enum   | `planned \| active \| completed \| cancelled`.                   |
-| `--start <date>`       | string | `--start ""` clears.                                             |
-| `--target <date>`      | string | `--target ""` clears.                                            |
+| Flag                   | Type   | Notes                                                                          |
+| ---------------------- | ------ | ------------------------------------------------------------------------------ |
+| `--project <ref>`      | string | Required when identifier is a name and workspace has >1 project.               |
+| `-n, --name <text>`    | string | Cannot be empty.                                                               |
+| `-d, --description <>` | string | `--description ""` clears.                                                     |
+| `-s, --status <value>` | enum   | `planned \| active \| completed \| cancelled`.                                 |
+| `--start <date>`       | string | `--start ""` clears.                                                           |
+| `--target <date>`      | string | `--target ""` clears.                                                          |
+| `--token-budget <n>`   | int    | Advisory token budget (LUM-644), positive integer; `--token-budget ""` clears. |
 
 At least one field required.
 
+**Token budget is advisory only (LUM-644):** the web Overview's tokens KPI card shows burn vs budget, and when the MEASURED burn exceeds the budget an advisory alert appears in the Risk & pending queue. Nothing is ever blocked by it — no hard gate. Unmeasured burn reads as unknown, never as over/under budget.
+
+**When to suggest**: when the user wants to cap/track token spend on a milestone ("给这个 milestone 设 token 预算 / budget"), or asks why the Overview shows an over-budget alert.
+
 **Status rolls up automatically (LUM-624):** milestone status follows task completion — PLANNED → ACTIVE when any task starts, → COMPLETED when every task is DONE (stamps `completedAt`, triggers the retro summary), and COMPLETED → ACTIVE when a non-DONE task (re)appears. A manual `--status planned/active/completed` that contradicts task reality gets reconciled back on the next task event or detail read; `--status cancelled` and archived milestones are human terminal choices the rollup never touches. You normally don't need `--status completed` by hand anymore.
 
+**The close is gated by exit criteria (LUM-643):** when the milestone has exit criteria (see `milestone criteria` below), any row not adjudicated MET — unadjudicated (PENDING) **or** NOT_MET — refuses `--status completed` with **409**, and holds the LUM-624 auto-rollup fail-closed (all tasks DONE keeps the milestone ACTIVE, no retro fires). There is **no CLI/agent override**: the only escape hatch is a human closing via the web with an explicit override (`?force=1` + optional note), stamped on the milestone as a persistent trail (`completedOverride*` — who/when/note, never auto-cleared). To open the gate legitimately, adjudicate the contract with `lumo milestone criteria verdict`.
+
 ```bash
 lumo milestone update "Q3 Launch" --status active
 lumo milestone update "Q3 Launch" --target 2026-09-15
 lumo milestone update "Q3 Launch" --description ""
+lumo milestone update "Q3 Launch" --token-budget 50000000
+lumo milestone update "Q3 Launch" --token-budget ""
+```
+
+### `lumo milestone criteria set <identifier> --file <criteria.json> [--human]` — submit the exit contract
+
+Milestone-level **exit criteria** (LUM-643) — the close contract, mirroring the task-level acceptance contract where it transfers. Key differences from `task criteria`: there is **no `verifierType` / no `checkpointer`** — exit criteria are **adjudicated (裁定)**, not machine-verified — and each item requires only `statement` + `referentKind`. The **steward session (LUM-640) is the intended drafting & adjudicating subject** (drafting is a governance action; session provenance is recorded on every row); `--human` records a transcribed HUMAN_EDIT revision instead.
+
+The file is a JSON array:
+
+```json
+[
+  {
+    "statement": "Every LUM-64x migration is applied on prod (migrate status clean)",
+    "referentKind": "EXTERNAL_FACT"
+  },
+  {
+    "statement": "All milestone read models render the new fields",
+    "referentKind": "AGENT_CONSTRUCTED_STATE"
+  }
+]
+```
+
+Semantics: **full-group replace** — existing rows with a verdict are tombstoned (their adjudication trail survives for audit), verdict-free rows are hard-deleted. The contract **locks with 409 once the milestone is COMPLETED** (reopen to edit). Archived milestones also refuse with 409.
+
+```bash
+lumo milestone criteria set "Q3 Launch" --file exit-criteria.json
+lumo milestone criteria set "Q3 Launch" --file exit-criteria.json --human
+```
+
+### `lumo milestone criteria list <identifier>` — print the exit contract
+
+One line per criterion — `<id>  [MET|NOT_MET|PENDING]  SOURCE ⟨REFERENT⟩  statement` — plus an indented `↳` detail line (date · evidence · note) for adjudicated rows, and a trailing gate-state line: either `All exit criteria MET — the close gate is open.` or `N unresolved (pending or NOT_MET) — the close gate refuses status→COMPLETED until adjudicated (human override only via web).`
+
+```bash
+lumo milestone criteria list "Q3 Launch"
 ```
 
+### `lumo milestone criteria verdict <identifier> <criterion> --met|--unmet` — adjudicate one criterion
+
+Records the adjudication (裁定) on one exit criterion — verdict, who, when, and the adjudicating session (LUM-640 steward provenance) are stamped server-side; re-adjudication overwrites in place (latest verdict wins). `<criterion>` accepts the full id or a **≥6-char unique id prefix** from `criteria list` (ambiguous/unknown selectors list candidates and exit 1).
+
+| Flag                   | Type    | Notes                                                                                                 |
+| ---------------------- | ------- | ----------------------------------------------------------------------------------------------------- |
+| `--met` / `--unmet`    | boolean | Exactly one required.                                                                                 |
+| `--note <text>`        | string  | Why this verdict (recommended).                                                                       |
+| `--evidence <pointer>` | string  | **Required for `--met` on an `EXTERNAL_FACT` criterion** (422 otherwise) — the fact it was read from. |
+| `--project <ref>`      | string  | Required when identifier is a name and workspace has >1 project.                                      |
+
+**Grounding gate (LUM-602/605 reuse):** `--met` on `EXTERNAL_FACT` without `--evidence` → **422** (re-ground or honestly re-declare the criterion `AGENT_CONSTRUCTED_STATE`); a `PENDING_OUTCOME` criterion can **never** be adjudicated MET (its truth lands post-delivery — use the outcome well). `--unmet` never needs evidence.
+
+```bash
+lumo milestone criteria verdict "Q3 Launch" cmexit0001 --met --evidence "prisma migrate status @ prod, 2026-07-02" --note "all LUM-64x applied"
+lumo milestone criteria verdict "Q3 Launch" cmexit0002 --unmet --note "read model not wired yet"
+```
+
+### When to suggest `milestone criteria`
+
+- A steward session planning a milestone ("what does done mean for this milestone", "draft exit criteria") → `criteria set`.
+- Before recommending `milestone update --status completed`, or when it just bounced with 409 → `criteria list` to see what holds the gate, then `verdict` per criterion.
+- User asks "can we close this milestone / what's blocking the close" → `criteria list` (the gate-state line answers it).
+
 ### `lumo milestone delete <identifier>` — delete a milestone
 
 Requires `--yes`. No interactive prompt — CLI is agent-friendly. Tasks under the milestone keep their data; their `milestoneId` is cleared.

package/assets/skill/references/tasks.md

@@ -177,10 +177,14 @@ one-line reason. Read-only — it does **not** bind or load context. Pick one fr
 the list, then run `lumo session attach <LUM-N>` + `lumo task context <LUM-N>`.
 
 Ranking is lexicographic: **priority** (URGENT→LOW) first, then **active-sprint
-membership**, then **due date** (earlier first), then in-flight status
-(IN_PROGRESS / IN_REVIEW ahead of TODO). DONE tasks are excluded. The active
-sprint lookup is best-effort — if it fails the command still recommends, just
-without the sprint boost.
+membership**, then **dependency topology** (LUM-645: tasks with an open
+CONFIRMED blocker sort after workable ones; among workable peers the task that
+directly unblocks the most open tasks ranks first), then **due date** (earlier
+first), then in-flight status (IN_PROGRESS / IN_REVIEW ahead of TODO). DONE
+tasks are excluded. The active sprint lookup is best-effort — if it fails the
+command still recommends, just without the sprint boost. The topology counts
+come from the server (`/api/tasks/me`); against an older server without them
+the order is simply the pre-topology ranking.
 
 | Flag              | Type    | Notes                                                                   |
 | ----------------- | ------- | ----------------------------------------------------------------------- |
@@ -199,9 +203,9 @@ Top 3 recommended tasks (of 12 open):
 1. LUM-42  IN_PROGRESS  URGENT  Fix Slack OAuth redirect
      ↳ URGENT · active sprint · due 2026-06-03 (overdue) · in progress
 2. LUM-48  TODO         HIGH    Investigate slow query
-     ↳ HIGH · active sprint
+     ↳ HIGH · active sprint · unblocks 2 tasks
 3. LUM-12  TODO         MEDIUM  Add rate limiting
-     ↳ MEDIUM · due 2026-06-10
+     ↳ MEDIUM · blocked by 1 open dep · due 2026-06-10
 
 Next: lumo session attach LUM-42 && lumo task context LUM-42
 ```

package/dist/cli/src/commands/milestone-criteria-list.js

@@ -0,0 +1,80 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.formatExitCriteriaRows = formatExitCriteriaRows;
+exports.milestoneCriteriaList = milestoneCriteriaList;
+const config_1 = require("../lib/config");
+const api_1 = require("../lib/api");
+const resolve_1 = require("../lib/resolve");
+const sanitize_1 = require("../lib/sanitize");
+/**
+ * Render exit-criterion rows for stdout. One line per criterion —
+ * `<id>  [MET|NOT_MET|PENDING]  SOURCE ⟨REFERENT⟩  statement` — plus an
+ * indented verdict detail line when adjudicated. Shared by `criteria list`,
+ * the `criteria set` echo and `criteria verdict`.
+ */
+function formatExitCriteriaRows(criteria) {
+    const lines = [];
+    for (const c of criteria) {
+        const verdict = c.verdict ?? 'PENDING';
+        lines.push(`${c.id}  [${verdict}]  ${c.source} ⟨${c.referentKind}⟩  ${(0, sanitize_1.sanitizeField)(c.statement)}`);
+        if (c.verdict) {
+            const parts = [];
+            if (c.verdictAt)
+                parts.push(`at ${c.verdictAt.slice(0, 10)}`);
+            if (c.verdictEvidence)
+                parts.push(`evidence: ${(0, sanitize_1.sanitizeField)(c.verdictEvidence)}`);
+            if (c.verdictNote)
+                parts.push(`note: ${(0, sanitize_1.sanitizeField)(c.verdictNote)}`);
+            if (parts.length > 0)
+                lines.push(`  ↳ ${parts.join(' · ')}`);
+        }
+    }
+    return lines.length > 0 ? lines.join('\n') + '\n' : '';
+}
+/** `lumo milestone criteria list <milestone>` — print the exit contract. */
+async function milestoneCriteriaList(identifier, opts) {
+    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);
+    const base = (0, api_1.trimTrailingSlash)(apiUrl);
+    let resolved;
+    try {
+        resolved = await (0, resolve_1.resolveMilestoneId)(base, creds.token, identifier, opts.project);
+    }
+    catch (err) {
+        console.error(`Error: ${err instanceof Error ? err.message : String(err)}`);
+        return 1;
+    }
+    let res;
+    try {
+        res = await fetch(`${base}/api/milestones/${resolved.id}/criteria`, {
+            headers: { Authorization: `Bearer ${creds.token}` },
+        });
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        console.error(`Error: could not reach Lumo API at ${apiUrl} (${msg})`);
+        return 1;
+    }
+    if (res.status === 401) {
+        console.error('Error: API key invalid or revoked. Run `lumo auth login`.');
+        return 1;
+    }
+    if (!res.ok) {
+        const body = (await res.json().catch(() => null));
+        console.error(`Error: exit-criteria list failed (HTTP ${res.status})${body?.error ? `: ${(0, sanitize_1.sanitizeField)(body.error)}` : ''}`);
+        return 1;
+    }
+    const data = (await res.json());
+    if (data.criteria.length === 0) {
+        process.stdout.write(`No exit criteria on this milestone — draft them and submit with lumo milestone criteria set ${identifier} --file <criteria.json>\n`);
+        return;
+    }
+    process.stdout.write(formatExitCriteriaRows(data.criteria));
+    process.stdout.write(data.unresolvedCount === 0
+        ? 'All exit criteria MET — the close gate is open.\n'
+        : `${data.unresolvedCount} unresolved (pending or NOT_MET) — the close gate refuses status→COMPLETED until adjudicated (human override only via web).\n`);
+}

package/dist/cli/src/commands/milestone-criteria-set.js

@@ -0,0 +1,145 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseExitCriteriaJson = parseExitCriteriaJson;
+exports.milestoneCriteriaSet = milestoneCriteriaSet;
+const config_1 = require("../lib/config");
+const api_1 = require("../lib/api");
+const resolve_1 = require("../lib/resolve");
+const doc_input_1 = require("../lib/doc-input");
+const path_guard_1 = require("../lib/path-guard");
+const sanitize_1 = require("../lib/sanitize");
+const milestone_criteria_list_1 = require("./milestone-criteria-list");
+const REFERENT_KINDS = [
+    'EXTERNAL_FACT',
+    'AGENT_CONSTRUCTED_STATE',
+    'PENDING_OUTCOME',
+];
+/**
+ * Client-side shape gate: fail fast on obviously malformed JSON before the
+ * round-trip. Full validation stays server-side. The file is a JSON array;
+ * one object per criterion: { statement, referentKind } — no verifierType /
+ * checkpointer (milestone exit criteria are adjudicated, not machine-run).
+ */
+function parseExitCriteriaJson(raw) {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (err) {
+        return {
+            ok: false,
+            error: `file is not valid JSON (${err instanceof Error ? err.message : String(err)})`,
+        };
+    }
+    if (!Array.isArray(parsed)) {
+        return { ok: false, error: 'file must be a JSON array of criteria' };
+    }
+    if (parsed.length === 0) {
+        return { ok: false, error: 'file contains an empty array' };
+    }
+    for (const [i, item] of parsed.entries()) {
+        if (item === null || typeof item !== 'object' || Array.isArray(item)) {
+            return { ok: false, error: `item ${i} is not an object` };
+        }
+        const o = item;
+        if (typeof o.statement !== 'string' || o.statement.trim() === '') {
+            return { ok: false, error: `item ${i} is missing "statement"` };
+        }
+        if (typeof o.referentKind !== 'string' ||
+            !REFERENT_KINDS.includes(o.referentKind)) {
+            return {
+                ok: false,
+                error: `item ${i} needs "referentKind" — one of ${REFERENT_KINDS.join(' | ')}`,
+            };
+        }
+    }
+    return { ok: true, items: parsed };
+}
+/**
+ * `lumo milestone criteria set <milestone> --file <criteria.json> [--human]`
+ * — submit the whole exit contract (LUM-643, full-group replace; adjudicated
+ * rows are tombstoned server-side so their verdict trail survives). Default
+ * source is AGENT_DRAFT (the steward draft); `--human` records a transcribed
+ * HUMAN_EDIT revision. Locked with 409 once the milestone is COMPLETED.
+ */
+async function milestoneCriteriaSet(identifier, opts) {
+    if (!opts.file) {
+        console.error('Error: --file <criteria.json> is required. The file is a JSON array of { statement, referentKind }.');
+        return 1;
+    }
+    const pathVerdict = (0, path_guard_1.checkArtifactFilePath)(opts.file);
+    if (!pathVerdict.ok) {
+        if (pathVerdict.reason === 'unreadable') {
+            console.error(`Error: ${(0, doc_input_1.unreadableFileMessage)(opts.file)}`);
+        }
+        else {
+            console.error(`Error: refusing to read ${opts.file} — ${pathVerdict.detail}. ` +
+                `criteria --file must be a non-sensitive path inside the project directory.`);
+        }
+        return 1;
+    }
+    let raw;
+    try {
+        raw = await (0, doc_input_1.readFileUtf8)(pathVerdict.resolved);
+    }
+    catch {
+        console.error(`Error: ${(0, doc_input_1.unreadableFileMessage)(opts.file)}`);
+        return 1;
+    }
+    const parsed = parseExitCriteriaJson(raw);
+    if (!parsed.ok) {
+        console.error(`Error: ${parsed.error}`);
+        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);
+    const base = (0, api_1.trimTrailingSlash)(apiUrl);
+    let resolved;
+    try {
+        resolved = await (0, resolve_1.resolveMilestoneId)(base, creds.token, identifier, opts.project);
+    }
+    catch (err) {
+        console.error(`Error: ${err instanceof Error ? err.message : String(err)}`);
+        return 1;
+    }
+    const headers = {
+        Authorization: `Bearer ${creds.token}`,
+        'Content-Type': 'application/json',
+    };
+    // Steward/session provenance (LUM-640) — recorded on each drafted row.
+    const sessionId = process.env.CLAUDE_CODE_SESSION_ID;
+    if (sessionId)
+        headers['X-Lumo-Session-Id'] = sessionId;
+    let res;
+    try {
+        res = await fetch(`${base}/api/milestones/${resolved.id}/criteria`, {
+            method: 'PUT',
+            headers,
+            body: JSON.stringify({
+                source: opts.human ? 'HUMAN_EDIT' : 'AGENT_DRAFT',
+                criteria: parsed.items,
+            }),
+        });
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        console.error(`Error: could not reach Lumo API at ${apiUrl} (${msg})`);
+        return 1;
+    }
+    if (res.status === 401) {
+        console.error('Error: API key invalid or revoked. Run `lumo auth login`.');
+        return 1;
+    }
+    if (!res.ok) {
+        const body = (await res.json().catch(() => null));
+        console.error(`Error: exit-criteria set failed (HTTP ${res.status})${body?.error ? `: ${(0, sanitize_1.sanitizeField)(body.error)}` : ''}`);
+        return 1;
+    }
+    const data = (await res.json());
+    process.stdout.write(`Exit contract set (${data.criteria.length} criteria) — adjudicate with lumo milestone criteria verdict\n`);
+    process.stdout.write((0, milestone_criteria_list_1.formatExitCriteriaRows)(data.criteria));
+}

package/dist/cli/src/commands/milestone-criteria-verdict.js

@@ -0,0 +1,129 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveCriterionSelector = resolveCriterionSelector;
+exports.milestoneCriteriaVerdict = milestoneCriteriaVerdict;
+const config_1 = require("../lib/config");
+const api_1 = require("../lib/api");
+const resolve_1 = require("../lib/resolve");
+const sanitize_1 = require("../lib/sanitize");
+const milestone_criteria_list_1 = require("./milestone-criteria-list");
+/**
+ * Resolve a criterion selector (full id or a ≥6-char unique id prefix)
+ * against the milestone's active contract. Ambiguous / unknown selectors
+ * list candidates and fail — mirrors `task deps` edge selection.
+ */
+function resolveCriterionSelector(selector, criteria) {
+    const exact = criteria.find(c => c.id === selector);
+    if (exact)
+        return { ok: true, id: exact.id };
+    if (selector.length < 6) {
+        return {
+            ok: false,
+            error: `criterion selector "${selector}" is too short — pass the id (or a prefix of at least 6 chars) from \`lumo milestone criteria list\``,
+        };
+    }
+    const hits = criteria.filter(c => c.id.startsWith(selector));
+    if (hits.length === 1)
+        return { ok: true, id: hits[0].id };
+    if (hits.length === 0) {
+        return {
+            ok: false,
+            error: `no exit criterion matches "${selector}" — see \`lumo milestone criteria list\``,
+        };
+    }
+    const candidates = hits
+        .map(h => `  ${h.id}  ${h.statement.slice(0, 60)}`)
+        .join('\n');
+    return {
+        ok: false,
+        error: `ambiguous selector "${selector}" matches ${hits.length} criteria:\n${candidates}`,
+    };
+}
+/**
+ * `lumo milestone criteria verdict <milestone> <criterion> --met|--unmet`
+ * — adjudicate (裁定) one exit criterion (LUM-643). The steward session
+ * (LUM-640) is the intended adjudicating subject; who/when/session are
+ * stamped server-side. Grounding gate: `--met` on an EXTERNAL_FACT criterion
+ * requires `--evidence`, and a PENDING_OUTCOME criterion can never be MET —
+ * both rejected with 422 server-side.
+ */
+async function milestoneCriteriaVerdict(identifier, criterionSelector, opts) {
+    if (opts.met === opts.unmet) {
+        console.error('Error: pass exactly one of --met or --unmet');
+        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);
+    const base = (0, api_1.trimTrailingSlash)(apiUrl);
+    let resolved;
+    try {
+        resolved = await (0, resolve_1.resolveMilestoneId)(base, creds.token, identifier, opts.project);
+    }
+    catch (err) {
+        console.error(`Error: ${err instanceof Error ? err.message : String(err)}`);
+        return 1;
+    }
+    // Fetch the active contract to resolve the criterion selector client-side.
+    let listRes;
+    try {
+        listRes = await fetch(`${base}/api/milestones/${resolved.id}/criteria`, {
+            headers: { Authorization: `Bearer ${creds.token}` },
+        });
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        console.error(`Error: could not reach Lumo API at ${apiUrl} (${msg})`);
+        return 1;
+    }
+    if (!listRes.ok) {
+        console.error(`Error: exit-criteria list failed (HTTP ${listRes.status})`);
+        return 1;
+    }
+    const { criteria } = (await listRes.json());
+    const selector = resolveCriterionSelector(criterionSelector, criteria);
+    if (!selector.ok) {
+        console.error(`Error: ${selector.error}`);
+        return 1;
+    }
+    const headers = {
+        Authorization: `Bearer ${creds.token}`,
+        'Content-Type': 'application/json',
+    };
+    // Adjudicating-session provenance (LUM-640) — stamped on the verdict.
+    const sessionId = process.env.CLAUDE_CODE_SESSION_ID;
+    if (sessionId)
+        headers['X-Lumo-Session-Id'] = sessionId;
+    let res;
+    try {
+        res = await fetch(`${base}/api/milestones/${resolved.id}/criteria/${selector.id}/verdict`, {
+            method: 'POST',
+            headers,
+            body: JSON.stringify({
+                verdict: opts.met ? 'MET' : 'NOT_MET',
+                ...(opts.note ? { note: opts.note } : {}),
+                ...(opts.evidence ? { evidence: opts.evidence } : {}),
+            }),
+        });
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        console.error(`Error: could not reach Lumo API at ${apiUrl} (${msg})`);
+        return 1;
+    }
+    if (res.status === 401) {
+        console.error('Error: API key invalid or revoked. Run `lumo auth login`.');
+        return 1;
+    }
+    if (!res.ok) {
+        const body = (await res.json().catch(() => null));
+        console.error(`Error: verdict failed (HTTP ${res.status})${body?.error ? `: ${(0, sanitize_1.sanitizeField)(body.error)}` : ''}`);
+        return 1;
+    }
+    const data = (await res.json());
+    process.stdout.write(`Adjudicated ${data.criterion.verdict} on exit criterion:\n`);
+    process.stdout.write((0, milestone_criteria_list_1.formatExitCriteriaRows)([data.criterion]));
+}

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

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.normalizeMilestoneStatus = normalizeMilestoneStatus;
+exports.normalizeTokenBudget = normalizeTokenBudget;
 exports.buildMilestoneUpdatePayload = buildMilestoneUpdatePayload;
 exports.formatMilestoneUpdateSummary = formatMilestoneUpdateSummary;
 exports.milestoneUpdate = milestoneUpdate;
@@ -22,6 +23,21 @@ function normalizeMilestoneStatus(value) {
         ? upper
         : null;
 }
+/**
+ * LUM-644: '' clears the budget (→ null, the nullable-flag convention);
+ * otherwise the value must be a positive integer within Postgres INT range.
+ * Invalid input → undefined (caller prints the error and exits 1).
+ */
+function normalizeTokenBudget(value) {
+    if (value === '')
+        return null;
+    if (!/^\d+$/.test(value))
+        return undefined;
+    const n = Number(value);
+    if (!Number.isSafeInteger(n) || n < 1 || n > 2_147_483_647)
+        return undefined;
+    return n;
+}
 function buildMilestoneUpdatePayload(opts) {
     const payload = {};
     const flagsGiven = [];
@@ -45,6 +61,12 @@ function buildMilestoneUpdatePayload(opts) {
         payload.targetDate = opts.target === '' ? null : opts.target;
         flagsGiven.push('--target');
     }
+    if (opts.tokenBudget !== undefined) {
+        // The caller validated eagerly (normalizeTokenBudget); '' means clear.
+        payload.tokenBudget =
+            opts.tokenBudget === '' ? null : Number(opts.tokenBudget);
+        flagsGiven.push('--token-budget');
+    }
     return { payload, flagsGiven };
 }
 function fmtDate(v) {
@@ -72,6 +94,11 @@ function formatMilestoneUpdateSummary(before, after) {
     if (after.targetDate !== undefined) {
         changes.push(`target → ${fmtDate(after.targetDate)}`);
     }
+    if (after.tokenBudget !== undefined) {
+        changes.push(after.tokenBudget === null
+            ? 'token budget → ∅'
+            : `token budget → ${after.tokenBudget.toLocaleString('en-US')}`);
+    }
     return `Updated milestone "${beforeName}": ${changes.join(', ')}`;
 }
 async function milestoneUpdate(identifier, opts) {
@@ -85,12 +112,18 @@ async function milestoneUpdate(identifier, opts) {
         }
         normalizedStatus = n;
     }
+    // Validate token budget eagerly (LUM-644): positive integer, or '' to clear.
+    if (opts.tokenBudget !== undefined &&
+        normalizeTokenBudget(opts.tokenBudget) === undefined) {
+        console.error(`Error: invalid token budget "${opts.tokenBudget}". Provide a positive integer (e.g. 5000000), or "" to clear.`);
+        return 1;
+    }
     const { payload, flagsGiven } = buildMilestoneUpdatePayload({
         ...opts,
         ...(normalizedStatus !== undefined && { status: normalizedStatus }),
     });
     if (flagsGiven.length === 0) {
-        console.error('Error: provide at least one field to update (--name, --description, --status, --start, --target)');
+        console.error('Error: provide at least one field to update (--name, --description, --status, --start, --target, --token-budget)');
         return 1;
     }
     const creds = (0, config_1.readCredentials)();

package/dist/cli/src/index.js

@@ -101,6 +101,9 @@ const milestone_remove_1 = require("./commands/milestone-remove");
 const milestone_summary_1 = require("./commands/milestone-summary");
 const milestone_reorder_1 = require("./commands/milestone-reorder");
 const milestone_move_1 = require("./commands/milestone-move");
+const milestone_criteria_set_1 = require("./commands/milestone-criteria-set");
+const milestone_criteria_list_1 = require("./commands/milestone-criteria-list");
+const milestone_criteria_verdict_1 = require("./commands/milestone-criteria-verdict");
 const sprint_create_1 = require("./commands/sprint-create");
 const sprint_list_1 = require("./commands/sprint-list");
 const sprint_show_1 = require("./commands/sprint-show");
@@ -605,13 +608,14 @@ milestoneCmd
     .action(wrap((identifier, options) => (0, milestone_show_1.milestoneShow)(identifier, options)));
 milestoneCmd
     .command('update <identifier>')
-    .description('Update a milestone. Provide at least one of --name, --description, --status, --start, --target. Use "" to clear nullable fields.')
+    .description('Update a milestone. Provide at least one of --name, --description, --status, --start, --target, --token-budget. Use "" to clear nullable fields.')
     .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 (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)')
+    .option('--token-budget <tokens>', 'Advisory token budget, positive integer (empty string to clear). Overview shows burn vs budget; over-budget raises a risk-queue alert — never a hard gate.')
     .action(wrap((identifier, options) => (0, milestone_update_1.milestoneUpdate)(identifier, options)));
 milestoneCmd
     .command('delete <identifier>')
@@ -657,6 +661,30 @@ milestoneCmd
     .option('--before <ref>', 'Place <ref> immediately before this milestone')
     .option('--after <ref>', 'Place <ref> immediately after this milestone')
     .action(wrap((ref, options) => (0, milestone_move_1.milestoneMove)(ref, options)));
+const milestoneCriteria = milestoneCmd
+    .command('criteria')
+    .description('Milestone-level exit criteria — the close contract (LUM-643). Drafted and adjudicated by the milestone steward (LUM-640) or a human; unresolved criteria refuse status→COMPLETED (human override via web only).');
+milestoneCriteria
+    .command('set <identifier>')
+    .description('Submit the whole exit contract from a JSON file (full replace; adjudicated rows are tombstoned, their verdict trail survives). Default = steward/agent draft; --human records a transcribed HUMAN_EDIT revision. Locked with 409 once the milestone is COMPLETED.')
+    .requiredOption('--file <path>', 'JSON array of criteria: [{"statement","referentKind":"EXTERNAL_FACT"|"AGENT_CONSTRUCTED_STATE"|"PENDING_OUTCOME"}] — no verifierType/checkpointer (exit criteria are adjudicated, not machine-run)')
+    .option('--human', 'Record a human contract revision (HUMAN_EDIT) transcribed from the conversation')
+    .option('--project <ref>', 'Project name or slug (when identifier is a name)')
+    .action(wrap((identifier, options) => (0, milestone_criteria_set_1.milestoneCriteriaSet)(identifier, options)));
+milestoneCriteria
+    .command('list <identifier>')
+    .description('List a milestone’s exit criteria: id, verdict (MET | NOT_MET | PENDING), provenance, referent kind, statement — plus whether the close gate is open.')
+    .option('--project <ref>', 'Project name or slug (when identifier is a name)')
+    .action(wrap((identifier, options) => (0, milestone_criteria_list_1.milestoneCriteriaList)(identifier, options)));
+milestoneCriteria
+    .command('verdict <identifier> <criterion>')
+    .description('Adjudicate (裁定) one exit criterion: --met or --unmet, with optional --note. Grounding gate: --met on an EXTERNAL_FACT criterion requires --evidence (422 otherwise), and a PENDING_OUTCOME criterion can never be MET. <criterion> = id or ≥6-char id prefix from `criteria list`.')
+    .option('--met', 'Adjudicate the criterion MET')
+    .option('--unmet', 'Adjudicate the criterion NOT_MET')
+    .option('--note <text>', 'Adjudication note (why this verdict)')
+    .option('--evidence <pointer>', 'Evidence pointer backing a MET on EXTERNAL_FACT (URL, commit SHA, CI run, DB probe …)')
+    .option('--project <ref>', 'Project name or slug (when identifier is a name)')
+    .action(wrap((identifier, criterion, options) => (0, milestone_criteria_verdict_1.milestoneCriteriaVerdict)(identifier, criterion, options)));
 const sprintCmd = program
     .command('sprint')
     .description('Inspect sprints from the terminal');

package/dist/cli/src/lib/rank-tasks.js

@@ -5,8 +5,9 @@
  * of human-readable reason factors.
  *
  * Ordering is lexicographic (explainable over a tunable magic score), honoring
- * "priority first": priority → active-sprint membership → dueDate → in-flight
- * status → updatedAt desc tiebreak.
+ * "priority first": priority → active-sprint membership → dependency topology
+ * (unblocked before blocked, then most open tasks released) → dueDate →
+ * in-flight status → updatedAt desc tiebreak.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.rankTasks = rankTasks;
@@ -38,11 +39,28 @@ function statusRank(status) {
 function inActiveSprint(task, activeSprintIds) {
     return task.sprintId !== null && activeSprintIds.has(task.sprintId);
 }
+/** Missing counts (older server) read as 0 — no topology signal, no reorder. */
+function blockedByOpen(task) {
+    return task.blockedByOpenCount ?? 0;
+}
+function unblocksOpen(task) {
+    return task.unblocksOpenCount ?? 0;
+}
 function deriveReasons(task, activeSprintIds, now) {
     const reasons = [task.priority];
     if (inActiveSprint(task, activeSprintIds)) {
         reasons.push('active sprint');
     }
+    const blocked = blockedByOpen(task);
+    const unblocks = unblocksOpen(task);
+    if (blocked > 0) {
+        reasons.push(blocked === 1
+            ? 'blocked by 1 open dep'
+            : `blocked by ${blocked} open deps`);
+    }
+    else if (unblocks > 0) {
+        reasons.push(unblocks === 1 ? 'unblocks 1 task' : `unblocks ${unblocks} tasks`);
+    }
     if (task.dueDate) {
         const day = task.dueDate.slice(0, 10);
         const due = new Date(task.dueDate).getTime();
@@ -64,6 +82,16 @@ function rankTasks(tasks, activeSprintIds, now) {
         const sb = inActiveSprint(b, activeSprintIds) ? 0 : 1;
         if (sa !== sb)
             return sa - sb;
+        // Dependency topology (LUM-645): workable-now before blocked, then the
+        // task that releases the most open work. Both 0 when the server doesn't
+        // send counts — the comparator falls through unchanged.
+        const ba = blockedByOpen(a) > 0 ? 1 : 0;
+        const bb = blockedByOpen(b) > 0 ? 1 : 0;
+        if (ba !== bb)
+            return ba - bb;
+        const ub = unblocksOpen(b) - unblocksOpen(a);
+        if (ub !== 0)
+            return ub;
         const dv = dueValue(a.dueDate) - dueValue(b.dueDate);
         if (dv !== 0 && !Number.isNaN(dv))
             return dv;

package/package.json

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