npm - @lumoai/cli - Versions diffs - 1.57.0 → 1.58.0 - Mend

@lumoai/cli 1.57.0 → 1.58.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (8) hide show

package/assets/skill/SKILL.md +40 -115
package/assets/skill/references/criteria.md +49 -0
package/assets/skill/references/ideas.md +82 -0
package/assets/skill/references/initiatives.md +28 -0
package/assets/skill/references/plan-runs.md +27 -0
package/assets/skill/references/sessions.md +4 -2
package/assets/skill/references/task-context.md +1 -1
package/package.json +1 -1

package/assets/skill/SKILL.md CHANGED Viewed

@@ -27,6 +27,9 @@ The command catalog below is a **map**: it lists every command grouped by domain
 | `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 deps add/list/confirm/dismiss/rm` (dependency edges)                              | [references/task-deps.md](references/task-deps.md)             |
+| `idea*` — capture pool, lifecycle, evidence, comments                                   | [references/ideas.md](references/ideas.md)                     |
+| `plan`, `plan status` — the idea→plan converter run                                     | [references/plan-runs.md](references/plan-runs.md)             |
+| `initiative create/list` (`LUM-INIT-<n>`)                                               | [references/initiatives.md](references/initiatives.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)                   |
@@ -44,14 +47,14 @@ The command catalog below is a **map**: it lists every command grouped by domain
 ## Command catalog
-**Onboarding / auth / update** — see [onboarding.md](references/onboarding.md)
+### Onboarding / auth / update — see [onboarding.md](references/onboarding.md)
 - `lumo setup [--user|--project] [--force] [--agent <token>]` — install skill files + hooks
 - `lumo auth login` / `lumo auth logout` — paste an API key / clear credentials
 - `lumo whoami` — show current identity (email, workspace, key)
 - `lumo update` — upgrade the CLI to the latest npm release
-**Task context & retrieval** — see [task-context.md](references/task-context.md)
+### Task context & retrieval — see [task-context.md](references/task-context.md)
 - `lumo task context <id>` — load task background (memory, source cards, PR review todos, prior sessions)
 - `lumo task slack show <id> <contextId>` — full stored Slack thread
@@ -61,7 +64,7 @@ The command catalog below is a **map**: it lists every command grouped by domain
 - `lumo task pr show <id> <number>` — synced PR metadata (v1)
 - `lumo task lineage <id>` — read-only causal-trail audit: fragments that fed the task + each one's disclosure tag/outcome, the run's token/loop cost, a disclosure-funnel summary, and a Top-5 "operations by token cost"; `--signal` appends workspace-level usage signal-health (see [task-context.md](references/task-context.md))
-**Tasks** — see [tasks.md](references/tasks.md)
+### Tasks — see [tasks.md](references/tasks.md)
 - `lumo task create <title> [flags]` — create a task. **Mid-task** (your session is bound to an in-flight task) it requires `--rework-of <id>` (redirects you to fix the existing task — creates nothing) or `--new-scope` (genuinely new, out-of-scope work). On a send-back, fix in place / amend the contract instead of spinning off a new task — see [verify.md](references/verify.md) and [criteria.md](references/criteria.md).
 - `lumo task update <id> [flags]` — patch status/title/priority/assignee/milestone/sprint/tags; `--claimable`/`--not-claimable` set the agent-claimable marker (LUM-646)
@@ -70,79 +73,25 @@ The command catalog below is a **map**: it lists every command grouped by domain
 - `lumo task show <id>` — print one task's detail
 - `lumo task comment <id> <body>` — leave a comment
-**Ideas (team-level capture pool)**
-- `lumo idea "<statement>" [--context <text>]` — capture a team-level idea into the pool in <10s. Provenance is grabbed opportunistically and never blocks the capture: the current `CLAUDE_CODE_SESSION_ID` (→ sourceSessionId) and the session's bound task (→ sourceTaskId, null when nothing is bound). Prints an **I-prefixed** id (`✓ 想法 LUM-I42 已入池`) — the `I` keeps ideas from colliding with task ids (`LUM-42`) in the same team namespace. Ideas are team-scoped (no project); the workspace's default team owns them. The unprocessed (CAPTURED) pool is what the Phase-2 transformer consumes.
-  - **When to suggest**: the user has a stray idea/thought/improvement they want to park without derailing the current task ("记一下这个想法", "capture this idea", "add to the backlog of ideas"). Prefer this over `task create` for un-triaged sparks — an idea is above projects and isn't yet actionable work.
-  - **Example**:
-    ```bash
-    lumo idea "Add a quick-capture keyboard shortcut" --context "raised in standup"
-    ```
-- `lumo idea list` — print the team idea pool **newest-first**, one line per idea: the `LUM-I<n>` id, status (`CAPTURED` | `DEVELOPING` | `PLANNED` | `DROPPED`) and statement. Reads `GET /api/ideas`, which returns the whole pool (every status), not just the unprocessed slice. Empty pool prints `No ideas.`. The same pool is browsable/searchable in web at `/workspace/<slug>/ideas` (sidebar → Ideas), where a PLANNED idea links to the plan run that materialised it and the status filter hides DROPPED by default.
-  - **When to suggest**: the user wants to see what's parked in the idea pool / "看看想法池" / "list the ideas" / triage before running `lumo plan`.
-  - **Example**:
-    ```bash
-    lumo idea list
-    ```
-- `lumo idea update <id> --status <captured|developing|planned|dropped>` — move an idea through its lifecycle (LUM-679). `<id>` is the `LUM-I<n>` id (a bare number also resolves); `--status` is case-insensitive. The four states are `CAPTURED` (pooled) → `DEVELOPING` (in triage / pre-work) → `PLANNED` (consumed by an initiative/plan), with `DROPPED` the terminal discard. Allowed transitions: `CAPTURED↔DEVELOPING`, `DEVELOPING→PLANNED`, and **any non-terminal → DROPPED**; nothing transitions out of `DROPPED`, and `CAPTURED→PLANNED` is not a manual move (only the converter's materialisation lands an idea in PLANNED). An illegal move is rejected with a clear error (400); an unknown id → 404.
-  - **When to suggest**: the user wants to triage the pool by hand — start pre-work on an idea ("开始预研这个想法" → `developing`), or discard one ("废弃/丢掉这个想法" → `dropped`). The status control also lives on the Idea detail page in web.
-  - **Example**:
-    ```bash
-    lumo idea update LUM-I42 --status developing
-    lumo idea update LUM-I42 --status dropped
-    ```
-- `lumo idea slack add/show/rm <idea> ...`, `lumo idea web add/show/rm <idea> ...`, `lumo idea figma add/list/rm/refresh/context <idea> ...` (LUM-681) — attach & inspect evidence (Slack threads, web links, Figma design links) on an idea, mirroring the `task slack/web/figma` source-card commands but hitting `/api/ideas/:id/...`. `<idea>` is the `LUM-I<n>` id. `show`/`context` are Tier-2 retrieval (stored snapshot / fetched body / cached design metadata, no live re-fetch) and stamp the disclosure funnel like their task-side counterparts; `figma refresh` re-fetches metadata for every link on the idea.
-  - **When to suggest**: the user wants to attach supporting evidence (a Slack discussion, a spec doc link, a Figma mock) to an idea before it goes through `lumo plan` — the converter carries this evidence forward into the resulting task/initiative. Prefer attaching to the idea over waiting until after conversion.
-  - **Example**:
-    ```bash
-    lumo idea web add LUM-I42 https://example.com/spec
-    lumo idea web show LUM-I42 wl_1
-    lumo idea web rm LUM-I42 wl_1
-    lumo idea slack add LUM-I42 https://myteam.slack.com/archives/C1/p123
-    lumo idea slack show LUM-I42 ctx_1
-    lumo idea slack rm LUM-I42 ctx_1
-    lumo idea figma add LUM-I42 https://www.figma.com/file/abc/Mock
-    lumo idea figma list LUM-I42
-    lumo idea figma context LUM-I42 cfl_1
-    lumo idea figma refresh LUM-I42
-    lumo idea figma rm LUM-I42 cfl_1
-    ```
-- `lumo idea comment <id> <body>` — post a comment on an idea (LUM-680). `<id>` is the `LUM-I<n>` id (a bare number also resolves) or a cuid; the body is plain text — quote it to pass spaces/newlines. Ideas reuse the task Comment model via a polymorphic `ideaId`; the thread is flat (no replies). Posting also records a `COMMENT_ADDED` entry on the idea's activity timeline. Comments/activity also render on the Idea detail slide-over in web.
-- `lumo idea comments list <id> [--full]` — print an idea's comment thread (oldest first), capped to the output budget like `task comments list`; `--full` prints every comment. Empty thread → `(no comments)`.
-  - **When to suggest**: the user wants to discuss or annotate a parked idea ("给这个想法加条评论", "comment on the idea"), or review an idea's discussion/history ("看看这个想法的评论/活动"). For the activity timeline (status changes, statement edits, materialisation) there is no CLI reader — it's shown on the Idea detail slide-over in web.
-  - **Example**:
-    ```bash
-    lumo idea comment LUM-I42 "Let's scope this for next sprint"
-    lumo idea comments list LUM-I42
-    ```
-**Plan runs (design-thinking 转换器)**
-- `lumo plan [--abandon-active]` — start a converter run that turns the team's captured idea pool + current priority into an executable plan through a 3-gate recoverable state machine (聚类→对齐→成计划). Freezes the input snapshot at start and enforces **one active run per team**: if a run is already active it refuses and points to `lumo plan status`; `--abandon-active` abandons the prior run first, then starts fresh. On success it prints (and opens) the **gate-A** web deep-link (`/workspace/<slug>/plan/<runId>`). The CLI only triggers — **all editing and gate confirmation happen in web**.
-- `lumo plan status` — print the active run's current stage (working segment or the open `*_READY` gate) and the deep-link to act on its next gate; with no active run, prompts to run `lumo plan`.
-  - **When to suggest**: the user wants to turn the parked idea pool into a plan / "跑一下转换器" / "start a planning run" / "把想法变成计划"; or asks where an in-flight plan run stands ("plan 到哪一步了", "plan status"). The gate work itself is web-only — the CLI hands off the deep-link.
-  - **Example** — check where the active run stands:
-    ```bash
-    lumo plan status
-    ```
-**Initiatives (team-level, LUM-INIT-<n>)**
-- `lumo initiative create "<goal>" [--assumption <text>]` — create a team-level Initiative **directly, no plan run required** (`planRunId=null`, status `ACTIVE`). Prints the `LUM-INIT-<n>` id; `--assumption` records the bet (赌注旁注) behind it. A blank goal is rejected (400). Converter-materialised initiatives (from `lumo plan`) live in the same list.
-  - **When to suggest**: the user wants to stand up a strategic initiative directly — "建一个 initiative" / "create an initiative" / "开一个举措" — without running the converter.
-  - **Example**:
-    ```bash
-    lumo initiative create "Ship the initiatives browse surface" --assumption "teams curate initiatives directly"
-    ```
-- `lumo initiative list` — print the team's initiatives newest-first, one line per initiative: the `LUM-INIT-<n>` id, status (`ACTIVE` | `DONE` | `DROPPED`) and goal. Browsable in web at `/workspace/<slug>/initiatives` (sidebar → Initiatives), where each links to its lineage (consumed ideas + attached tasks).
-  - **When to suggest**: the user wants to see the team's initiatives / "看看 initiatives" / "list the initiatives".
-  - **Example**:
-    ```bash
-    lumo initiative list
-    ```
-**Task dependencies** — see [task-deps.md](references/task-deps.md)
+### Ideas (team-level capture pool) — see [ideas.md](references/ideas.md)
+- `lumo idea "<statement>" [--context <text>]` — capture an un-triaged spark into the team pool (<10s); prints an **I-prefixed** id (`LUM-I42`) that cannot collide with task ids
+- `lumo idea list` — the whole pool newest-first (every status); also browsable at `/workspace/<slug>/ideas`
+- `lumo idea update <id> --status <captured|developing|planned|dropped>` — manual lifecycle move; `CAPTURED→PLANNED` is converter-only
+- `lumo idea slack|web|figma …` — attach & inspect evidence on an idea, mirroring the task-side source cards
+- `lumo idea comment <id> <body>` · `lumo idea comments list <id> [--full]` — flat comment thread on an idea
+### Plan runs (design-thinking 转换器) — see [plan-runs.md](references/plan-runs.md)
+- `lumo plan [--abandon-active]` — start a converter run (聚类→对齐→成计划) over the captured pool + current priority; one active run per team; prints the gate-A web deep-link
+- `lumo plan status` — the active run's stage plus the deep-link to its next gate. Gate work is **web-only**
+### Initiatives (team-level, `LUM-INIT-<n>`) — see [initiatives.md](references/initiatives.md)
+- `lumo initiative create "<goal>" [--assumption <text>]` — create directly, no plan run required
+- `lumo initiative list` — team initiatives newest-first; lineage browsable in web
+### Task dependencies — see [task-deps.md](references/task-deps.md)
 - `lumo task deps list <id>` — list dependency edges both directions, grouped CONFIRMED / SUGGESTED / DISMISSED (each row: short edge id + other task + detected evidence)
 - `lumo task deps add <id> --blocked-by <LUM-N>` — declare a manual hard dependency (CONFIRMED)
@@ -151,52 +100,47 @@ The command catalog below is a **map**: it lists every command grouped by domain
 - `lumo task deps rm <id> <edge> --yes` — delete an edge (refuses without `--yes`)
 - `<edge>` = short edge-id prefix (≥6 chars) or the other task's identifier; ambiguous/unknown selectors list candidates and exit 1. See [tasks.md](references/tasks.md)
-**Acceptance criteria (contract)** — see [criteria.md](references/criteria.md)
+### Acceptance criteria (contract) — see [criteria.md](references/criteria.md)
 - `lumo task criteria set <task> --file <criteria.json> [--human] [--cause <tag>]` — submit the whole contract (full-group replace). Default = agent draft (AGENT_DRAFT, editable until DONE); `--human` = a HUMAN_EDIT revision transcribed from the conversation; `--cause` annotates why the contract drifted. See [criteria.md](references/criteria.md)
 - `lumo task criteria list <task>` — print the contract (id, MACHINE/HUMAN, provenance source@round, checkpointer)
-**Verification (machine acceptance loop)** — see [verify.md](references/verify.md)
+### Verification (machine acceptance loop) — see [verify.md](references/verify.md)
 - `lumo verify [task] --note "<self-report>" [--timeout <seconds>]` — run every MACHINE criterion's checkpointer locally and report a structured PASS/FAIL verdict per criterion. **`--note` is required** when a round will be posted: a one-line self-report ("我改了 X,因为 Y 可验收") frozen as your task's claim (source AGENT) the moment the round passes into IN_REVIEW, then checked against the diff for faithfulness. No note → no round posted (none burned). The round cap is the workspace's `verificationMaxRounds` (default 3) — read the actual budget off the `Round N/M` line the command prints, never assume a number. All-pass → task to IN_REVIEW (agent stops); a fail on the last round → escalate to human. **Run this before claiming a task is done.**
 - `lumo task status [task] [--json]` — read-only acceptance self-check (no LLM): the contract with each criterion's latest verdict, verification history/round, last failure reasons, `nextActions` (the unmet criteria), and any OPEN boundary crossings (fails closed — `null`/`⚠` means "could not confirm", not safe). **Run it first when resuming a task or after a round was rejected.**
 - `lumo verdict [task] --pass | --fail` — acceptance verdicts. `--pass` deep-links to the human verdict bar (records nothing). `--fail --reason <enum> …` records an AGENT send-back → IN_PROGRESS. **An unresolved send-back blocks the DONE transition with 409.**
 - `lumo crossing explain <id> --note "<text>"` — append an agent self-explanation ("申辩") to a boundary crossing; append-only, **never clears the crossing or unblocks Done** (disposition stays web + human-only). A review aid, not a self-clear.
-**Cost (per-operation token read-out)** — see [task-context.md](references/task-context.md)
+### Cost (per-operation token read-out) — see [task-context.md](references/task-context.md)
 - `lumo cost [--task <id>|--session <id>|--since <date>] [--by tool|model|member|session] [--json]` — per-operation token cost read-out, attributing each model step's token delta to the tool(s) it ran. Scope is mutually exclusive (default = workspace last-30-days). For the per-task Top-5 inline, see `lumo task lineage`.
-**Priority (team-level declaration)** — see [priority.md](references/priority.md)
+### Priority (team-level declaration) — see [priority.md](references/priority.md)
 - `lumo priority [text]` — declare the team's current priority (a 1-3 sentence plain-text statement). With `text`, records it directly; with no argument, prompts interactively. **Append-only**: a new declaration supersedes the old by a later `effectiveFrom` — nothing is ever overwritten or deleted.
 - `lumo priority list` — print the append history newest-first (the current declaration is marked `*`).
-**Criteria audit** — workspace-level referent-kind analytics
+### Criteria audit — see [criteria.md](references/criteria.md)
 - `lumo criteria audit` — workspace-level read-out: count of acceptance criteria by effective referent kind (EXTERNAL_FACT / AGENT_CONSTRUCTED_STATE / PENDING_OUTCOME / UNVERIFIED_ASSERTION / UNCLASSIFIED) + the self-confirming-green ratio
-**Outcome well (post-hoc oracle)** — see [outcome.md](references/outcome.md)
+### Outcome well (post-hoc oracle) — see [outcome.md](references/outcome.md)
 - `lumo outcome show <task>` — read the post-hoc outcome well: the **falsifier** verdict (`REJECTED` | `INCONCLUSIVE` — never a "pass") plus its backing rejection signals. `INCONCLUSIVE` = no rejection on record, **not** "satisfied".
 - `lumo outcome record <task> --note "<what reality did>" [--kind <kind>]` — record a human-observed post-hoc **rejection** of a delivery (revert / rollback / CI regression / downstream redirect / bypass). Append-only; **there is no "mark satisfied" counterpart** — the well only asserts rejection. `--note` is required (the observed referent).
 - `lumo outcome rate [--min N] [--json]` — workspace **trust × post-hoc-fate** join (LUM-603, LUM-606): per delivery-time **verification-friction** bucket (`no-verification` / `single-round` / `multi-round-or-sendback` — two raw counts frozen at delivery, replacing the saturating forecast-confidence axis), the post-hoc REJECTED rate from the well. Honest by construction — thin buckets read `insufficient` (no fabricated rate), the single-round-vs-multi comparison stays `inconclusive` until CIs separate, and the rate is a **lower bound** (no signal = INCONCLUSIVE, never satisfied). Bucket names are value-neutral — direction is decided by the correlation, never welded into the label. Under-sampled today by design — the skeleton produces real strata once the well fills.
-**Fidelity read-out (mechanical change-pattern)** — see [fidelity.md](references/fidelity.md)
+### Fidelity read-out (mechanical change-pattern) — see [fidelity.md](references/fidelity.md)
 - `lumo fidelity show <task> [--json]` — per delivery snapshot (LUM-609), a **composition table, not a single score**: (1) the **grounding** of the frozen contract — grounded (`EXTERNAL_FACT`, a machine-checkable upper bound) / self-confirming (`AGENT_CONSTRUCTED_STATE` + `UNVERIFIED_ASSERTION`) / inconclusive (`PENDING_OUTCOME` + `UNCLASSIFIED`, surfaced not swallowed) + the full effective-kind tally; (2) the **independence** signal — criteria `ADDED`/`UPDATED` at round>0 (after work started) that the delivery rode on = backward-inference suspects. Purely mechanical (timing + op + grounding) — **no direction verdict**. A no-snapshot task is reported explicitly (not a pass). Zero new storage — reads the snapshot + `CRITERION_CHANGED` trail.
-```bash
-lumo fidelity show LUM-42
-lumo fidelity show LUM-42 --json
-```
-**Artifacts & Figma** — see [artifacts-figma.md](references/artifacts-figma.md)
+### Artifacts & Figma — see [artifacts-figma.md](references/artifacts-figma.md)
 - `lumo task artifact add/update/list/show/rm` — record spec/plan products on a task
 - `lumo task figma add/list/rm/refresh` — attach & manage Figma designs
-**Projects & milestones** — see [milestones.md](references/milestones.md)
+### Projects & milestones — see [milestones.md](references/milestones.md)
 - `lumo project list` — list projects (slugs feed `--project`)
 - `lumo milestone list/create/show/update/delete` — milestone CRUD (`show` includes a Sprint-coverage section)
@@ -208,7 +152,7 @@ lumo fidelity show LUM-42 --json
 - `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)
+### Documents — CRUD/sharing → [docs.md](references/docs.md); **editing live docs** (raw/section/patch/append/diff/rebuild) → [doc-editing.md](references/doc-editing.md)
 - `lumo doc create/update/show/list/delete` — document CRUD; `doc update` takes `--if-revision <n>` (mismatch → 409, re-read and retry) and is structure-guarded (drops to tables/rows/headings → 422 unless `--allow-shrink`)
 - `lumo doc show <doc> --raw` / `--section "<heading>"` — print the byte-identical markdown source (the only legal edit base; never the lossy HTML→md render), whole or one heading-addressed slice
@@ -219,14 +163,14 @@ lumo fidelity show LUM-42 --json
 - `lumo doc move/bind/unbind/share/unshare/share-list` — reparent · task linkage · member sharing
 - `lumo doc import-gdoc` / `lumo doc sync` — Google Doc import & re-sync
-**Sprints** — see [sprints.md](references/sprints.md)
+### Sprints — see [sprints.md](references/sprints.md)
 - `lumo sprint list/create/show/update/delete` — sprint CRUD (`show` includes Progress / Health / Blockers)
 - `lumo sprint start/close` — status transitions (no `--status` flag)
 - `lumo sprint add/remove <id> <task>` — bind/unbind a task
 - `lumo sprint summary [--retry]` — AI retro
-**Memory** — see [memory.md](references/memory.md)
+### Memory — see [memory.md](references/memory.md)
 - `lumo task memory add/list` · `lumo project memory add/list` — record/curate Memory (TASK vs PROJECT)
 - `lumo memory show <id>` — show one memory's full card (category + content) by id (progressive disclosure from a one-line index entry)
@@ -235,7 +179,7 @@ lumo fidelity show LUM-42 --json
 - `lumo memory push [--dry-run]` — upsync locally-authored memories from `<memory-dir>/outbox/*.json` to the team
 - `lumo memory fold [project-ref] --dry-run` — read-only PREVIEW of the autonomous topic-fold pass (folding runs via a daily cron; no manual apply, no `unfold`). See [memory.md](references/memory.md)
-**Sessions** — see [sessions.md](references/sessions.md)
+### Sessions — see [sessions.md](references/sessions.md)
 - `lumo session attach <id>` — bind this session to a task (then run `task context`). **Lifetime lock**: re-attaching to the same task is a no-op; attaching to a _different_ task is refused with 409 — start a new Claude Code session instead. No `--force`, no `session detach`.
 - `lumo session attach --steward <milestone>` — bind this session to a **milestone** as a **STEWARD (governance) session** (LUM-640): plan & accept only. Governance passes (task create/update, criteria set incl. `--human`, deps confirm/dismiss, `verdict --fail` with session provenance, milestone add/remove, milestone triage (LUM-646 claimable), all reads); implementation is gated (`lumo verify` → 409 **without burning a round**; moving a task to in_progress assigned to yourself → 409); commits/PRs produced anyway are recorded as milestone-scoped boundary crossings (fail-closed; disposition stays web+human-only, no CLI clear path). Same lifetime lock: same milestone idempotent, any other attach (a task, or a different milestone) → 409; multiple stewards per milestone are fine. See [sessions.md](references/sessions.md)
@@ -243,31 +187,12 @@ lumo fidelity show LUM-42 --json
 - End-of-session housekeeping is fully automatic (no command). On DONE the server runs three best-effort silent passes: Layer-1 memory curation, fragment-usage audit, and blocked-tag automation. See [sessions.md](references/sessions.md)
 - Git-suggest at session start (suggests `session attach`, never auto-binds) + Layer-2 project-memory review — see the reference
-**Worktrees (local dev tooling)** — see [worktree.md](references/worktree.md)
+### Worktrees (local dev tooling) — see [worktree.md](references/worktree.md)
 - `lumo worktree add <LUM-N> [slug]` — scaffold `.worktrees/<LUM-N>` + node_modules symlink off origin/main; run from the main checkout
 - `lumo worktree rm <LUM-N> --yes` — remove a worktree (keeps the branch unless `--delete-branch`)
 - `lumo worktree list` — list `.worktrees/` worktrees (task id, branch, dirty, node_modules link)
-## Criteria audit
-```bash
-lumo criteria audit
-```
-`lumo criteria audit` — workspace-level acceptance-criteria analytics. Calls `GET /api/criteria/audit` and prints two things:
-1. **Declared-kind distribution** — count of criteria by effective referent kind:
-   - `EXTERNAL_FACT` — declared as externally observable (git SHA, CI status, DB row) and the checkpointer invokes real external tooling
-   - `AGENT_CONSTRUCTED_STATE` — passes by checking output the agent itself produced
-   - `PENDING_OUTCOME` — deferred to post-hoc falsifier
-   - `UNVERIFIED_ASSERTION` — declared `EXTERNAL_FACT` but the checkpointer does **not** actually invoke external tooling (git/CI/HTTP); auto-downgraded. As of LUM-605 this is an **enforced gate, not just a label**: `lumo task criteria set` warns on it, and `lumo verify` blocks a PASS on it with **422 (no round burned)** until it's re-grounded or honestly re-declared `AGENT_CONSTRUCTED_STATE` (see references/criteria.md "referentKind")
-   - `UNCLASSIFIED` — legacy rows predating the `referentKind` field (null in DB)
-2. **Self-confirming-green headline ratio** — `(AGENT_CONSTRUCTED_STATE + UNVERIFIED_ASSERTION) / classified`. Criteria in these two buckets pass by confirming only the agent's own work, not an independent external state.
-**When to suggest**: when the user wants to audit how much of the workspace's "green" criteria are self-confirming vs externally anchored; when diagnosing whether acceptance criteria have real external hooks or are circular.
 ## Next-step hints (the trailing `Next:` block)
 `task create`, `task update`, `session attach`, `task context` and `next` end with a short `Next:` block naming what to do now — attach an unbound session, draft a missing contract, run `lumo verify`, read `task status` after a rejected round, explain an open boundary crossing, or stop and wait when the task is IN_REVIEW.
@@ -300,7 +225,7 @@ Don't guess these:
 1. `lumo session attach LUM-42` — bind this session (the binding is a lifetime lock; one session = one task)
 2. `lumo task context LUM-42` — load background; review unresolved items, PR-review todos, the description
-3. **If the task has no acceptance criteria** (context shows the draft reminder, not 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)
+3. **If the task has no acceptance criteria** (context shows the draft reminder, not 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**. When a `### Reference class (outside view)` block follows the reminder, draft against it — it lists how similar delivered tasks actually failed; treat it as material to reason from, never as a checklist to cover. See [criteria.md](references/criteria.md)
 4. Do the work
 5. **Before claiming done: `lumo verify`** — the machine half of the acceptance loop. Fix failures and re-run (the cap is workspace-configurable — see the `Round N/M` line in the output). All-pass → task moves to IN_REVIEW and you stop. See [verify.md](references/verify.md)

package/assets/skill/references/criteria.md CHANGED Viewed

@@ -12,6 +12,35 @@ If `lumo task context` / session-start shows the draft reminder ("This task has
 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").
 3. `lumo task criteria set <task> --file <criteria.json>` — submit.
+### The reference-class block (outside view) — LUM-497
+Below the draft reminder you may see a `### Reference class (outside view)` block: mechanical statistics over **similar delivered tasks** — the send-back reasons they hit, how often their contract was still being written after work started, and the boundary crossings they tripped. It exists because an agent drafting its own acceptance criteria is systematically optimistic: you write down what you intend to build, not what tasks like this one historically got sent back for.
+```
+### Reference class (outside view)
+Based on: 14 delivered tasks in milestone "Trust and cognitive load"
+· Most common send-back reasons: evidence insufficient 5/14 · work did not match the criterion 3/14
+· Contract still being written after work started: 9/14 deliveries
+· Most common boundary crossing: edited a file a checkpointer depends on 3/14
+Tasks here most often come back for insufficient evidence — what will your key criteria point at as proof?
+```
+**How to use it:** read the failure modes, then ask which of them this task can plausibly hit, and let that change what you write. "Evidence insufficient" leads the class → decide what your key criteria will actually point at as proof. "Work did not match the criterion" leads → check that your statements describe outcomes rather than the steps you plan to take.
+**How NOT to use it — this is the failure mode the block itself is most likely to cause:** do not treat the lines as a checklist to be "covered". Adding one criterion per listed failure mode, or setting `evidenceRequired` on everything because evidence leads the distribution, inflates the criterion count without adding information and taxes every verification round. The trailing line is deliberately a **question, not an instruction** — answer it for this task.
+Reading the numbers honestly:
+- Counts are **raw fractions over a small class** (`5/14`), never percentages, on purpose — `5/14` is a handful of tasks, not a rate. Weight them accordingly.
+- The block names its own class and sample size (`Based on: N delivered tasks in <scope>`) — a milestone-level class is far more relevant to your task than a team-level fallback. Check which one you got.
+- **`Insufficient sample: …` is a correct, deliberate output**, not a failure or a missing feature. It means no scope reached the minimum class size (the block states the floor in its own message), and a distribution over fewer tasks would read as evidence while carrying none. Draft from the task itself and move on.
+- A class with no recorded send-backs, post-start contract edits or crossings says so explicitly. That is a stated fact about the class, not missing data.
+The block is derived server-side from delivery history; it is not a claim by any agent, and there is nothing to reply to or act on beyond your own drafting.
 **The contract is editable until DONE — changes after work starts leave a recorded drift trail.** Behaviour changes at two thresholds tracked by `Task.workStartedAt` (set the first time the task leaves TODO; never resets even if the task bounces back to TODO):
 | Stage                                                              | `criteria set` resubmit behaviour                                                                                                                                                                                                                                                                                                       |
@@ -214,9 +243,29 @@ lumo task criteria list LUM-42
 - **Session start** (bound task): the contract is the highest-priority section in the injection budget — ahead of memory/PR/Slack/Figma/web. If a still-open task has no criteria, the draft reminder is injected instead.
 - **`lumo session attach`**: prints the contract (or the draft reminder) right after binding.
+- **The reference-class block** rides on the draft reminder at all three of those surfaces, so it appears only when the task has no contract yet — the one moment it can still change what gets written. It is capped at a few lines, sits outside the injection budget, and is skipped silently if the read fails or the workspace has acceptance mode off.
 - **`lumo task context`**: the `## Acceptance criteria (contract)` section appears after the task description, before memory.
 - **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
 The contract is judged by `lumo verify` — run it before claiming the task is done. See [verify.md](verify.md) for the loop (a workspace-configurable round cap — `verificationMaxRounds`, default 3, shown as `Round N/M` in the output — IN_REVIEW on all-pass, escalation on a last-round fail).
+## `lumo criteria audit` — workspace referent-kind analytics
+```bash
+lumo criteria audit
+```
+`lumo criteria audit` — workspace-level acceptance-criteria analytics. Calls `GET /api/criteria/audit` and prints two things:
+1. **Declared-kind distribution** — count of criteria by effective referent kind:
+   - `EXTERNAL_FACT` — declared as externally observable (git SHA, CI status, DB row) and the checkpointer invokes real external tooling
+   - `AGENT_CONSTRUCTED_STATE` — passes by checking output the agent itself produced
+   - `PENDING_OUTCOME` — deferred to post-hoc falsifier
+   - `UNVERIFIED_ASSERTION` — declared `EXTERNAL_FACT` but the checkpointer does **not** actually invoke external tooling (git/CI/HTTP); auto-downgraded. As of LUM-605 this is an **enforced gate, not just a label**: `lumo task criteria set` warns on it, and `lumo verify` blocks a PASS on it with **422 (no round burned)** until it's re-grounded or honestly re-declared `AGENT_CONSTRUCTED_STATE` (see references/criteria.md "referentKind")
+   - `UNCLASSIFIED` — legacy rows predating the `referentKind` field (null in DB)
+2. **Self-confirming-green headline ratio** — `(AGENT_CONSTRUCTED_STATE + UNVERIFIED_ASSERTION) / classified`. Criteria in these two buckets pass by confirming only the agent's own work, not an independent external state.
+**When to suggest**: when the user wants to audit how much of the workspace's "green" criteria are self-confirming vs externally anchored; when diagnosing whether acceptance criteria have real external hooks or are circular.

package/assets/skill/references/ideas.md ADDED Viewed

@@ -0,0 +1,82 @@
+# Ideas (team-level capture pool)
+An **idea** is an un-triaged spark parked above the project layer — not yet actionable work. Ideas are team-scoped (no project); the workspace's default team owns them. Ids are **I-prefixed** (`LUM-I42`) so they cannot collide with task ids (`LUM-42`) in the same team namespace.
+The unprocessed (`CAPTURED`) pool is what the `lumo plan` converter consumes — see [plan-runs.md](plan-runs.md).
+## `lumo idea "<statement>" [--context <text>]`
+Capture an idea into the pool in under 10 seconds. Provenance is grabbed opportunistically and **never blocks the capture**: the current `CLAUDE_CODE_SESSION_ID` (→ `sourceSessionId`) and the session's bound task (→ `sourceTaskId`, null when nothing is bound). Prints `✓ 想法 LUM-I42 已入池`.
+**When to suggest**: the user has a stray idea / thought / improvement they want to park without derailing the current task ("记一下这个想法", "capture this idea", "add to the backlog of ideas"). Prefer this over `task create` for un-triaged sparks — an idea is above projects and isn't yet actionable work.
+```bash
+lumo idea "Add a quick-capture keyboard shortcut" --context "raised in standup"
+```
+## `lumo idea list`
+Print the pool **newest-first**, one line per idea: the `LUM-I<n>` id, status and statement. Reads `GET /api/ideas`, which returns the **whole** pool (every status), not just the unprocessed slice. Empty pool prints `No ideas.`
+The same pool is browsable/searchable in web at `/workspace/<slug>/ideas` (sidebar → Ideas), where a `PLANNED` idea links to the plan run that materialised it and the status filter hides `DROPPED` by default.
+**When to suggest**: the user wants to see what's parked ("看看想法池", "list the ideas"), or is triaging before running `lumo plan`.
+```bash
+lumo idea list
+```
+## `lumo idea update <id> --status <captured|developing|planned|dropped>`
+Move an idea through its lifecycle (LUM-679). `<id>` is the `LUM-I<n>` id (a bare number also resolves); `--status` is case-insensitive.
+| State        | Meaning                          |
+| ------------ | -------------------------------- |
+| `CAPTURED`   | pooled, un-triaged               |
+| `DEVELOPING` | in triage / pre-work             |
+| `PLANNED`    | consumed by an initiative / plan |
+| `DROPPED`    | terminal discard                 |
+Allowed transitions: `CAPTURED ↔ DEVELOPING`, `DEVELOPING → PLANNED`, and **any non-terminal → DROPPED**. Nothing transitions out of `DROPPED`. `CAPTURED → PLANNED` is **not** a manual move — only the converter's materialisation lands an idea in `PLANNED`. An illegal move is rejected with a clear error (400); an unknown id → 404.
+**When to suggest**: the user wants to triage by hand — start pre-work ("开始预研这个想法" → `developing`) or discard one ("废弃/丢掉这个想法" → `dropped`). The same control lives on the Idea detail page in web.
+```bash
+lumo idea update LUM-I42 --status developing
+lumo idea update LUM-I42 --status dropped
+```
+## Evidence on an idea — `slack` / `web` / `figma`
+`lumo idea slack add|show|rm`, `lumo idea web add|show|rm`, `lumo idea figma add|list|rm|refresh|context` (LUM-681) attach and inspect supporting evidence, mirroring the `task slack/web/figma` source-card commands but hitting `/api/ideas/:id/...`. `<idea>` is the `LUM-I<n>` id.
+`show` / `context` are **Tier-2 retrieval** (stored snapshot / fetched body / cached design metadata — no live re-fetch) and stamp the disclosure funnel like their task-side counterparts. `figma refresh` re-fetches metadata for every link on the idea.
+**When to suggest**: the user wants to attach evidence (a Slack discussion, a spec link, a Figma mock) to an idea **before** it goes through `lumo plan` — the converter carries that evidence forward into the resulting task/initiative. Prefer attaching to the idea over waiting until after conversion.
+```bash
+lumo idea web add LUM-I42 https://example.com/spec
+lumo idea web show LUM-I42 wl_1
+lumo idea web rm LUM-I42 wl_1
+lumo idea slack add LUM-I42 https://myteam.slack.com/archives/C1/p123
+lumo idea slack show LUM-I42 ctx_1
+lumo idea slack rm LUM-I42 ctx_1
+lumo idea figma add LUM-I42 https://www.figma.com/file/abc/Mock
+lumo idea figma list LUM-I42
+lumo idea figma context LUM-I42 cfl_1
+lumo idea figma refresh LUM-I42
+lumo idea figma rm LUM-I42 cfl_1
+```
+## Comments — `lumo idea comment` / `lumo idea comments list`
+`lumo idea comment <id> <body>` posts a comment (LUM-680). `<id>` is the `LUM-I<n>` id (a bare number or a cuid also resolves); the body is plain text — quote it to pass spaces/newlines. Ideas reuse the task `Comment` model via a polymorphic `ideaId`; the thread is **flat** (no replies). Posting also records a `COMMENT_ADDED` entry on the idea's activity timeline.
+`lumo idea comments list <id> [--full]` prints the thread oldest-first, capped to the output budget like `task comments list`; `--full` prints every comment. Empty thread → `(no comments)`.
+**When to suggest**: the user wants to discuss or annotate a parked idea ("给这个想法加条评论"), or review its discussion/history ("看看这个想法的评论/活动"). For the **activity timeline** (status changes, statement edits, materialisation) there is no CLI reader — it renders on the Idea detail slide-over in web.
+```bash
+lumo idea comment LUM-I42 "Let's scope this for next sprint"
+lumo idea comments list LUM-I42
+```

package/assets/skill/references/initiatives.md ADDED Viewed

@@ -0,0 +1,28 @@
+# Initiatives (team-level, `LUM-INIT-<n>`)
+An **Initiative** is a team-level strategic goal that tasks roll up to. Two origins land in the same list:
+- **Direct** — `lumo initiative create`, no plan run required (`planRunId = null`, status `ACTIVE`).
+- **Materialised** — produced by the `lumo plan` converter's gate C, carrying its lineage (see [plan-runs.md](plan-runs.md)).
+## `lumo initiative create "<goal>" [--assumption <text>]`
+Create an Initiative directly. Prints the `LUM-INIT-<n>` id. `--assumption` records the bet (赌注旁注) behind it — the thing that, if false, makes the initiative the wrong call. A blank goal is rejected (400).
+**When to suggest**: the user wants to stand up a strategic initiative directly — "建一个 initiative", "create an initiative", "开一个举措" — without running the converter.
+```bash
+lumo initiative create "Ship the initiatives browse surface" --assumption "teams curate initiatives directly"
+```
+## `lumo initiative list`
+Print the team's initiatives newest-first, one line each: the `LUM-INIT-<n>` id, status (`ACTIVE` | `DONE` | `DROPPED`) and goal.
+Browsable in web at `/workspace/<slug>/initiatives` (sidebar → Initiatives), where each links to its lineage — the ideas it consumed and the tasks attached to it.
+**When to suggest**: the user wants to see the team's initiatives ("看看 initiatives", "list the initiatives").
+```bash
+lumo initiative list
+```

package/assets/skill/references/plan-runs.md ADDED Viewed

@@ -0,0 +1,27 @@
+# Plan runs (design-thinking 转换器)
+A **plan run** turns the team's captured idea pool + the current priority declaration into an executable plan, through a 3-gate recoverable state machine: **聚类 → 对齐 → 成计划**.
+The CLI only **triggers and reports**. All editing and gate confirmation happen in **web** — the CLI hands off a deep-link.
+Inputs come from [ideas.md](ideas.md) (the `CAPTURED` pool) and [priority.md](priority.md) (the current declaration). Materialisation produces tasks plus, when the plan calls for one, an Initiative — see [initiatives.md](initiatives.md).
+## `lumo plan [--abandon-active]`
+Start a converter run. Freezes the input snapshot at start and enforces **one active run per team**: if a run is already active it refuses and points to `lumo plan status`. `--abandon-active` abandons the prior run first, then starts fresh.
+On success it prints (and opens) the **gate-A** web deep-link, `/workspace/<slug>/plan/<runId>`.
+Invoked bare (`lumo plan`) it starts a run; `lumo plan --abandon-active` clears a stuck one first. The command is a parent with its own action — `status` below is a subcommand added on top of it, not a required one.
+**When to suggest**: the user wants to turn the parked idea pool into a plan — "跑一下转换器", "start a planning run", "把想法变成计划".
+## `lumo plan status`
+Print the active run's current stage — either the working segment or the open `*_READY` gate — plus the deep-link to act on its next gate. With no active run, prompts to run `lumo plan`.
+**When to suggest**: the user asks where an in-flight run stands ("plan 到哪一步了", "plan status"). The gate work itself is web-only.
+```bash
+lumo plan status
+```

package/assets/skill/references/sessions.md CHANGED Viewed

@@ -91,7 +91,7 @@ What it does:
 - Reads `CLAUDE_CODE_SESSION_ID` from the environment (Claude Code sets it automatically); errors out if unset — must run from inside a Claude Code session.
 - Calls `POST /api/sessions/<session_id>/bind-task`, which sets the Session row's `taskId` and re-tags previously-untagged HookEvent rows in this session.
 - The binding lives entirely on the server (`Session.taskId`); subsequent hooks read it back via the session row. The CLI keeps no local sentinel.
-- Prints the task's **acceptance contract** (`## Acceptance criteria (contract)`) right after the bind confirmation — or, when a still-open task has none, the draft reminder to draft 3–7 criteria before the first line of code (see [criteria.md](criteria.md)). The same section is auto-injected at session start when already bound (highest priority in the injection budget, ahead of memory).
+- Prints the task's **acceptance contract** (`## Acceptance criteria (contract)`) right after the bind confirmation — or, when a still-open task has none, the draft reminder to draft 3–7 criteria before the first line of code, followed by the `### Reference class (outside view)` block when history supports one (see [criteria.md](criteria.md)). The same section is auto-injected at session start when already bound (highest priority in the injection budget, ahead of memory).
 After attaching, always run `lumo task context <identifier>` to load the task background.
@@ -176,7 +176,9 @@ The old end-of-session command was **removed**. The three passes it ran interact
 - confidently-unused → `used=false`
 - genuinely-uncertain edges stay `null` (honest "not voted", not "unused")
-Already-voted sessions are skipped; a cron backstop drains any backlog. **Why:** upgrades the flywheel signal from "co-loaded" (constant) to "actually used" (discriminative); `task context` then prefers each fragment's usage-based merge rate, falling back to the presence rate when usage samples are thin.
+Already-voted sessions are skipped; a cron backstop drains any backlog. **Why:** upgrades the flywheel signal from "co-loaded" (constant) to "actually used" (discriminative). `task context` then reports each fragment's **judged-used track record** — of the N tasks it appeared in, X were judged to have actually used it. That is a **lower bound** (never-audited appearances are excluded from the proven/retire calls), and it **replaced the retired merge-rate signal** (RFC LUM-535).
+> Don't confuse this with the used-vs-base **merge rate** still reported by `lumo task lineage --signal` ([task-context.md](task-context.md)) — that is a different, live metric for workspace signal-health, not the retired fragment-usefulness one.
 **3. Blocked-tag automation (server-side).** When a session crosses the same-tool failure threshold (**≥ 3** same-type failures, aggregated from `POST_TOOL_USE_FAILURE` grouped by tool name + `STOP_FAILURE` turn-level failures), the server **auto-applies the shared `blocked` tag** to the bound task. This inverts the old manual gate — no prompt, no human in the loop — and is safe via three safeguards:

package/assets/skill/references/task-context.md CHANGED Viewed

@@ -13,7 +13,7 @@ lumo task context LUM-42
 The command prints a markdown document to stdout with these sections, in order:
 1. **Task header** — identifier, title, status, description.
-2. **`## Acceptance criteria (contract)`** — shown right after the header. Each line `[MACHINE|HUMAN] statement`, with a `↳ check:` line for MACHINE checkpointers; HUMAN_EDIT / REVIEW_ADDED provenance tagged inline. A still-open task with none shows a draft reminder instead — draft 3–7 criteria **before writing code** (see [criteria.md](criteria.md)).
+2. **`## Acceptance criteria (contract)`** — shown right after the header. Each line `[MACHINE|HUMAN] statement`, with a `↳ check:` line for MACHINE checkpointers; HUMAN_EDIT / REVIEW_ADDED provenance tagged inline. A still-open task with none shows a draft reminder instead — draft 3–7 criteria **before writing code** — followed by a `### Reference class (outside view)` block giving the failure modes of similar delivered tasks, to draft against rather than to copy (see [criteria.md](criteria.md)).
 3. **Memory section** — cross-session learnings; trusted background context that persists, so you avoid re-learning decisions/constraints.
 4. **Inline source cards** — Slack / web / Figma / artifacts / documents / comments / Pull Requests (see "Context Retrieval" below).
 5. **`## PR review todos`** — mirrored PR review comments as a checkbox todo list. Each line-level comment shows `` `file:line` `` + reviewer's ask + GitHub comment link; each `changes_requested` review summary shows "🛑 Changes requested (whole PR)". Present only when the task's PR(s) have review comments. Each unchecked box is a TODO: resolve it, then reply on the PR (a Lumo comment mirrors back to GitHub).

package/package.json CHANGED Viewed

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