@lumoai/cli 1.38.0 → 1.40.0

package/assets/skill/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: lumo
-description: 'Use the Lumo CLI to work with Lumo (project management for dev teams) from the terminal: load task context, bind/wrap Claude Code sessions, and create/update/list/show/comment on tasks, projects, milestones, sprints, documents, artifacts, Figma links, dependencies, and team memory — plus acceptance criteria, machine verification (verify / task status), lineage audit, worktree scaffolding, and CLI setup/auth/update. Activate when the user mentions a Lumo task identifier (LUM-N) or the lumo CLI, in any language; asks to load task background or bind/check/wrap a session; manages any of the resources above in Lumo; is starting, resuming, or about to claim completion of a task; or asks what to work on next. Key triggers: "LUM-", "lumo", "task context", "session attach", "session wrap", "verify", "task status", "acceptance criteria", "milestone", "sprint", "docs", "memory", "deps", "lineage", "worktree", "design link", "what should I work on", "resume task".'
+description: 'Use the Lumo CLI to work with Lumo (project management for dev teams) from the terminal: load task context, bind Claude Code sessions, and create/update/list/show/comment on tasks, projects, milestones, sprints, documents, artifacts, Figma links, dependencies, and team memory — plus acceptance criteria, machine verification (verify / task status), lineage audit, worktree scaffolding, and CLI setup/auth/update. Activate when the user mentions a Lumo task identifier (LUM-N) or the lumo CLI, in any language; asks to load task background or bind/check a session; manages any of the resources above in Lumo; is starting, resuming, or about to claim completion of a task; or asks what to work on next. Key triggers: "LUM-", "lumo", "task context", "session attach", "verify", "task status", "acceptance criteria", "milestone", "sprint", "docs", "memory", "deps", "lineage", "worktree", "design link", "what should I work on", "resume task".'
 ---
 
 ## Prerequisites
@@ -32,7 +32,7 @@ The command catalog below is a **map**: it lists every command grouped by domain
 | `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/wrap`, git-suggest on start, Layer-2 review                      | [references/sessions.md](references/sessions.md)               |
+| `session attach/status`, 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
@@ -82,6 +82,7 @@ The command catalog below is a **map**: it lists every command grouped by domain
 - `lumo verify [task] [--timeout <seconds>]` — run every MACHINE criterion's checkpointer locally, report one structured PASS/FAIL verdict per criterion to the server, print next actions. Defaults to the session-bound task. Round cap 3: an all-pass round moves the task to IN_REVIEW (agent stops there); a round-3 fail escalates to a human (stop retrying). **Run this before claiming a task is done.**
 - `lumo task status [task] [--json]` — read-only acceptance self-check (no LLM, milliseconds): the contract with each criterion's latest verdict (REVIEW_ADDED provenance visible), verification history, current round, last round's failure reasons, a per-criterion **send-back lifecycle** line when applicable (`↳ send-back (rN) resolved in rM · PR #K` / `… open` — LUM-511 Phase 5), `nextActions` = the unmet criteria (the declarative "what's next" — no separate plan), and any OPEN (undispositioned) boundary crossings (count + per crossing category/severity/detail + a read-only attribution line `↳ by model=…·agent=…·session=…` naming who/what crossed, `unknown` when unresolved — LUM-469; `--json` adds an `openCrossings` field, each entry carrying an `attribution` object) — read-only awareness, disposition stays web + human-only (LUM-448). The crossings check fails closed (LUM-480): if the read errors, the block prints `⚠ Boundary-crossing check failed` instead of staying silent, and `--json` sets `openCrossings: null` (distinct from `[]` = a successful read with zero open — treat `null` as "could not confirm", not "safe"). Defaults to the session-bound task; `--json` emits a versioned payload (`version` field). **Run it first when resuming a task in a new session or after a verification round was rejected.**
 - `lumo verdict [task] --pass | --fail` — acceptance verdicts (LUM-422). `--pass` opens the browser to the human verdict bar focused on Pass (a deep link — **records nothing**; a passing data row is only ever a human's own click). `--fail --reason <enum> [--note <text>] [--criterion <id>…]` records an **AGENT send-back** (verifierType=AGENT, verdict hard-coded FAIL) and bounces the task to IN_PROGRESS. Defaults to the session-bound task. **An unresolved send-back (machine/AGENT/human FAIL) blocks the agent/CLI DONE transition with 409** — clear it (re-verify) before `task update --status done`.
+- `lumo crossing explain <id> --note "<text>"` — append an agent self-explanation ("申辩") to a boundary crossing (LUM-542). The **inverse** of dispositioning: this is the agent/CLI path (bearer-only; a clerk/human caller is refused), but it can **only append** an append-only note — it **never clears the crossing or unblocks Done** (disposition stays web + human-only, LUM-448). The note is shown to the human reviewer at disposition time and kept for later review, explicitly labeled _agent self-report · unverified_. Scope: `<id>` must be a crossing on the **session-bound task** (resolved from `$CLAUDE_CODE_SESSION_ID`; cross-task targets and unbound/mismatched sessions are rejected). Earlier explanations are immutable — a correction is a new note. **When to suggest:** after `lumo task status` (or the next pre-tool-use hook's one-time reminder) surfaces an OPEN crossing you believe is a false positive or want to leave a rationale for — record it here; it's a review aid, not a way to self-clear the gate.
 
 **Cost (per-operation token read-out)** — see [task-context.md](references/task-context.md)
 
@@ -127,12 +128,17 @@ The command catalog below is a **map**: it lists every command grouped by domain
 - `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)
 - `lumo memory promote <id>` / `lumo memory rm <id> --yes` — TASK→PROJECT / delete
+- `lumo memory sync [--project <ref>] [--dir <path>] [--dry-run] [--clean]` — downsync team memory into the local Claude Code memory store (`team/<id>.md` + a managed MEMORY.md block); only touches files it owns, never your own memory; `--dry-run` previews, `--clean` fully reverts (runs alongside session-start injection)
+- `lumo memory push [--project <ref>] [--dir <path>] [--dry-run]` — upsync locally-authored memories (`<memory-dir>/outbox/*.json`, each `{category, content}`) to the team via the existing create-project-memory pipeline (canonicalize/dedup/reconcile-on-write); pushed files leave the outbox on success
 
 **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 status` — show current binding
-- `lumo session wrap [--yes] [--dry-run] [--used <indices>]` — end-of-session panel: memory review + fragment-usage vote (`--used`, LUM-300) + blocked-tag prompt, then a read-only reminder when the bound task has ≥1 OPEN boundary crossing still undispositioned (silent only on a genuine empty read — no wrap-up noise; a crossings-check failure prints a "could not confirm" warning instead of staying silent, LUM-480; pointer is web + human-only, LUM-448). Usage is now also audited automatically when a task reaches DONE (evidence-gated, true-only — confident fragments marked used, the rest left NULL); `session wrap --used` remains the manual override and takes precedence for a session.
+- End-of-session housekeeping is fully automatic — the old end-of-session command was removed in LUM-544. When a task reaches DONE the server runs three evidence-gated passes, all best-effort and silent:
+  - **Layer-1 memory curation** — an LLM judge reviews the memories the task's sessions recorded and soft-invalidates only the clearly-wrong / self-contradictory ones (invalidate-not-delete; uncertain memories are left untouched). Promotion to project scope stays with the Layer-2 flow.
+  - **Fragment-usage audit** (LUM-314) — an LLM judge votes which injected context fragments were actually used: confidently-used edges → `used=true`, confidently-unused → `used=false`, genuinely-uncertain stay NULL.
+  - **Blocked-tag automation** (LUM-544 §3) — if a session crosses the same-tool failure threshold (≥3) the bound task is auto-tagged `blocked` (idempotent, attributed to the triggering session + model); the next observable progress on that task auto-removes the tag. Human-applied `blocked` tags are never auto-removed.
 - 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)

package/assets/skill/references/memory.md

@@ -29,6 +29,17 @@ lumo project memory add [<project>] --category convention --rule "..." --applies
 lumo memory show <memoryId>        # show one memory's full card by id
 lumo memory promote <memoryId>     # TASK → PROJECT
 lumo memory rm <memoryId> --yes    # hard delete
+
+# Downsync team memory into the local Claude Code memory store
+lumo memory sync                   # write team/<id>.md + a managed MEMORY.md block
+lumo memory sync --dry-run         # preview the reconcile plan, write nothing
+lumo memory sync --project <ref>   # target a specific project (default: bound session)
+lumo memory sync --clean           # remove everything sync owns (full rollback)
+lumo memory sync --no-anchor-check # skip the post-sync code-anchor staleness check
+
+# Upsync locally-authored memories to the team (reverse direction)
+lumo memory push                   # promote <memory-dir>/outbox/*.json to the team
+lumo memory push --dry-run         # list what would be pushed without sending
 ```
 
 When the session is bound (`lumo session attach <LUM-N>`), omit the identifier:
@@ -71,6 +82,73 @@ When a specific entry looks relevant to the task at hand, run
 `lumo memory show <id>` to pull its full body before acting on it — read the
 detail on demand instead of carrying every memory's content in context.
 
+### `lumo memory sync` (downsync to local Claude Code memory)
+
+Writes the team's project memory into the dev's local Claude Code memory store so
+Claude Code's **native recall** surfaces it — the direction LUM-535/536 chose over
+per-session `<untrusted-team-memory>` injection. This is P3 (the sync build); it
+runs **alongside** the existing injection (retiring injection is LUM-540), so
+during the transition both paths are active and overlap is expected, not a bug.
+
+- **Where it writes**: `~/.claude/projects/<encoded-cwd>/memory/` — team files as
+  `team/<memoryId>.md` (YAML frontmatter + a `metadata.lumo` ownership marker),
+  plus a delimited `<!-- lumo:team-memory:start/end -->` block in `MEMORY.md`.
+  `--dir <path>` overrides the resolved directory.
+- **Only touches what it owns**: a file is owned only if its frontmatter carries
+  `metadata.lumo.source: team`. Your own hand-written memory files and any
+  `MEMORY.md` lines outside the managed block are **never** read or written.
+- **Selection**: judge-used 履历 (LUM-539) ranks first, with relevance/cold-start
+  grace as backfill, capped to the resident-index budget — so the local index
+  stays compact.
+- **Routing (per recipient)**: the bundle is scoped to the calling dev — memories
+  are filtered by relevance to that dev's active (assigned, not-DONE) tasks in the
+  project, so different devs get differentiated sets rather than the whole corpus.
+  A dev with no active tasks falls back to the full budget-capped set.
+- **Reconcile / drift**: re-running is idempotent. A team file you edited locally
+  is detected (its on-disk hash diverged from the recorded `contentHash`) and
+  **skipped, never overwritten** — your edit is preserved and flagged as an
+  upsync candidate (the reverse direction is a later phase).
+- **Reversible**: `--dry-run` prints the add/update/remove/drift-skip plan without
+  writing; `--clean` removes every owned file + the managed block (full rollback).
+- **Code-anchor staleness check (LUM-547 P4b)**: after downsync, each synced memory's
+  code anchors (file paths, and backtick-wrapped symbols/flags) are checked against
+  this repo — resolved against **git-tracked** files (`git ls-files`) + exact
+  word-boundary grep, never the dirty working tree. A memory whose **every** anchor
+  is gone is reported to the server as a `stale-anchor` retire candidate (with the
+  dead anchors as evidence), feeding the P4a human-review retire pool. High-precision
+  by design: any surviving anchor spares the memory, and reporting never archives
+  anything — a human confirms retirement on the web. Skipped on `--dry-run` / `--clean`,
+  or with `--no-anchor-check`; a detection failure never fails the sync.
+- **Project**: resolved from the bound session unless `--project <ref>` is given.
+
+**When to suggest**: when a dev wants the team's accumulated memory available to
+Claude Code's native recall in their working copy (instead of, or in addition to,
+session-start injection) — run `lumo memory sync` in the project. Suggest
+`--dry-run` first to confirm the resolved directory and plan, and `--clean` to
+back the change out.
+
+### `lumo memory push` (upsync to the team)
+
+The reverse of `sync`: promote memories a dev authored locally up to the team
+store. Each candidate is a JSON file in `<memory-dir>/outbox/` shaped
+`{ "category": "convention", "content": { ... } }` (the same per-category content
+shape as `lumo project memory add`). `push` POSTs each to the **existing**
+create-project-memory endpoint, so it runs through the same canonicalize → dedup →
+**reconcile-on-write** pipeline (LUM-538) — no parallel upsync path — and a
+successful push removes the file from the outbox.
+
+- **Scope**: structured local memories (the lossless path). A team file you edited
+  locally is rendered markdown that cannot be reversed back to structured content,
+  so those (P1 drift candidates) are **reported** by `lumo memory sync`, not
+  auto-promoted — re-express the improvement as an outbox entry or via
+  `lumo project memory add`.
+- **Project**: resolved from the bound session unless `--project <ref>` is given.
+- `--dry-run` lists what would be pushed without sending.
+
+**When to suggest**: when a dev has captured a reusable lesson locally and wants it
+shared with the team — drop a `{category, content}` JSON in the memory `outbox/`
+and run `lumo memory push` (or just use `lumo project memory add` for a one-off).
+
 ### Reconcile-on-write & deduplication
 
 `memory add` does **not** unconditionally insert a new row. Before writing it:

package/assets/skill/references/sessions.md

@@ -33,7 +33,7 @@ just attach the correct task instead.
 
 When the session is bound, session-start may inject a **"🆕 Review needed: project memories auto-consolidated by the previous session"** section alongside the memory / PR-review blocks (LUM-165). It lists the **PROJECT-scope** memories that the member's **immediately-preceding session** auto-consolidated (Layer 2 runs asynchronously when a task is marked `done`). Each item shows its `id`.
 
-- **Why it's here:** Layer 2 promotions land async, so they can't be reviewed in the synchronous `session wrap` panel — they're surfaced at the _next_ session-start instead, when they've definitely landed.
+- **Why it's here:** Layer 2 promotions land async (after the task hits DONE), so they're surfaced at the _next_ session-start instead, when they've definitely landed.
 - **Show-once:** the section appears only at the session that immediately follows the one that produced the memories. It does **not** re-nag on later sessions, so act on it now or it scrolls off.
 - **Agent guidance:** briefly sanity-check each listed memory against the codebase/context. If one is wrong or over-generalized, remove it with `lumo memory rm <id> --yes` (ideally confirm with the user first). If they all look right, ignore the section and continue.
 
@@ -125,89 +125,47 @@ lumo session status
 
 When to suggest: the user asks "which task am I on", "what's this session bound to", or you need to decide whether to suggest `session attach` for a mentioned task ID.
 
-### `lumo session wrap [--yes] [--dry-run] [--used <indices>]` — wrap-up panel: memory review + fragment-usage vote + blocked-tag prompt
-
-Session-end wrap-up panel with **three sections, run in order**:
-
-**1. Memory review** — lists the Layer1 memories this session sedimented since the
-last review (deduped by a per-session watermark `Session.lastMemoryReviewAt`).
-Each new memory is shown as `[SCOPE] CATEGORY  headline`, numbered from 1. You
-curate with a single line: `d 1,3` deletes rows 1 and 3, `p 2` promotes row 2 to
-project scope, and they combine (`d 1,3 p 2`). **Enter (empty) keeps all**; `s`
-skips the section. Keeping all (Enter or `--yes`) still **advances the watermark**
-so the next wrap won't re-list reviewed memories; `s` leaves them for next time.
-Out-of-range indices are ignored. Deletes/promotes run server-side, scoped to
-memories this session created (you can't touch other sessions' memories through
-this panel). With no new memories the section prints "(no content)" and does nothing.
-
-**2. Fragment-usage vote (LUM-300)** — lists the context
-fragments this session **consumed** (its lineage edges: memory / slack / web /
-figma / PR / review-todo / session), numbered from 1 with a content snippet
-label. The agent records which it **actually used** via
-`lumo session wrap --used <indices>` (1-based, comma/space separated; `--used
-none` = used nothing). Voted fragments get `used=true`, the rest of the
-session's fragments `used=false`. **Without `--used` the section only lists the
-candidates and writes nothing** (edges stay `null` = not voted — honest, not
-"unused"). A session that already voted (`usedAt` set) is skipped. **Why:** it
-upgrades the flywheel signal from "co-loaded" (constant, no information) to
-"actually used" (varies → discriminative); `task context` then prefers each
-fragment's usage-based merge rate, falling back to the weaker presence rate when
-usage samples are thin. With no consumed fragments the section prints "(no content)".
-
-**3. Blocked check (blocked-tag prompt, LUM-153)** — if the **same kind of failure
-recurred ≥ 3 times** in this session (server-aggregated from
-`POST_TOOL_USE_FAILURE` events grouped by tool name, plus `STOP_FAILURE`
-turn-level failures), the section surfaces the dominant failure (`This session looks repeatedly stuck on <tool> (N failures).` + last error summary) and prompts `[y] tag / [s] skip` whether to
-flag the bound task with a **`blocked` tag**. **Prompt-only — never auto-flips
-status.** It uses a plain tag (no `TaskStatus` enum, no board column, **no
-schema migration**). The prompt is **suppressed** when: there's no bound task,
-the threshold isn't met, or the task **already** carries a `blocked` tag (the
-idempotent gate — there's no watermark, the existing tag is what prevents
-re-nagging). The default on empty input / `s` is **do nothing** (tagging is
-opt-in), so a stray Enter never tags the task. Confirming with an explicit `y`
-attaches the tag idempotently. **`--yes` does NOT auto-tag** — tagging the
-shared board requires an interactive `y`, so `--yes` (and non-TTY) prints the
-suggestion and moves on rather than silently flipping board state. When there's
-nothing to prompt, the section prints "(no content)".
-
-**After the panel — open-crossings reminder (LUM-448).** Once the three sections
-finish, `session wrap` prints a one-shot read-only reminder **if** the bound
-task has ≥1 OPEN (undispositioned) boundary crossing: `⚠ N open boundary
-crossing(s) on LUM-N still undispositioned:` then a line per crossing `• [SEVERITY]
-CATEGORY` and a web pointer. When the read genuinely comes back empty — or the
-session is unbound — it prints **nothing** (truly silent, not a "(no content)"
-line), so a clean task adds no wrap-up noise. **But a crossings-check failure is
-not silent (LUM-480):** if the read errors (network / server), it prints
-`⚠ Could not check boundary crossings on LUM-N (network/server error) — unable
-to confirm whether any are still undispositioned`, so a failed safety check never
-masquerades as "0 open / safe". **Awareness only:** it points at the web
-acceptance panel; there is **no CLI path** to disposition or clear a crossing.
-Disposition stays web + human-only (LUM-426/435/422) — an agent/CLI bearer cannot
-clear its own crossing from the terminal.
-
-```bash
-lumo session wrap                  # interactive: preview each section, choose per-section
-lumo session wrap --yes            # memories kept; blocked tag NOT auto-applied (needs interactive y)
-lumo session wrap --yes --used 1,3 # also record fragments 1 & 3 as used (the rest used=false)
-lumo session wrap --used none      # record that none of the injected fragments were used
-lumo session wrap --dry-run        # print all drafts only; never mutates, never advances watermarks
-```
-
-The usage vote is a two-step flow for agents: run `lumo session wrap` once to
-see the numbered fragment list, decide which you actually used, then re-run with
-`--used <indices>`. Re-running is safe — the other sections are watermark-guarded
-(reviewed memories won't re-list).
-
-- Requires `$CLAUDE_CODE_SESSION_ID` (must run inside Claude Code) and a bound
-  task (`lumo session attach <LUM-N>` first).
-- `--yes` keeps all memories (no deletes/promotes) while advancing the
-  memory-review watermark; for the blocked-tag section it prints the suggestion
-  but does **not** apply the tag.
-- `--dry-run` prints all drafts; never mutates memories/tags, never advances the
-  memory-review watermark.
-- Non-TTY without `--yes`: prints the drafts and does **not** mutate or tag (safe
-  default).
-
-When to suggest: at the end of a working session on a bound task, to review the
-memories it sedimented, vote which injected fragments were actually used, and
-flag the task `blocked` if it got repeatedly stuck — offer `lumo session wrap`.
+### Automatic end-of-session housekeeping (no command — LUM-544)
+
+The old end-of-session command was **removed in LUM-544**. The three passes it
+used to run interactively now happen **automatically server-side**, all
+evidence-gated, best-effort, and silent — there is nothing for the agent to run
+or confirm. Two fire when the bound task reaches **DONE** (`lumo task update <id>
+--status done`, which threads `CLAUDE_CODE_SESSION_ID` so attribution lands), one
+runs continuously off the failure/progress hooks.
+
+**1. Layer-1 memory curation (on DONE).** An LLM judge reviews the Layer-1
+memories each of the task's sessions recorded, against that session's event log,
+and **soft-invalidates only the clearly-wrong / self-contradictory ones**
+(invalidate-not-delete: the row flips to `INVALIDATED` and is excluded from
+injection but **kept for audit — never hard-deleted**). **Uncertain memories are
+left untouched** — the judge defaults to keeping. Promotion to project scope is
+**not** done here; that stays with the Layer-2 flow (surfaced at the next
+session-start, see above).
+
+**2. Fragment-usage audit (LUM-314, on DONE).** An LLM judge sees the fragments
+this session consumed (its lineage edges) plus the session's event log and votes
+which were **actually used**: confidently-used edges → **`used=true`**,
+confidently-unused → **`used=false`**, and **genuinely-uncertain edges stay
+`null`** (honest "not voted", not "unused"). Already-voted sessions are skipped;
+a cron backstop drains any backlog. **Why:** it 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.
+
+**3. Blocked-tag automation (LUM-544 §3, 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 LUM-153 manual `y` gate** — no prompt, no human in
+the loop — and is safe because of three safeguards: **(idempotent)** at most one
+active auto-block per task, so re-crossing is a no-op; **(auto-untag on
+progress)** the next observable progress on the task (a successful tool call or a
+non-failure turn end) removes the tag; **(attribution)** the triggering session +
+model are recorded. A **human-applied** `blocked` tag has no auto-block record and
+is **never** auto-removed by progress.
+
+When to suggest: nothing to suggest — these run on their own. If a teammate asks
+why a task shows `blocked`, explain it's the auto-block (repeated same-tool
+failures) and that it clears itself once the task makes progress; a human can also
+remove the tag manually from the board.

package/assets/skill/references/verify.md

@@ -186,6 +186,26 @@ could not confirm whether any are undispositioned` instead of staying silent.
   Silence means a successful read with zero open crossings, never a failed
   check — a hiccup can no longer masquerade as "all clear".
 
+### Responding to an open crossing — `lumo crossing explain` (LUM-542)
+
+When `lumo task status` surfaces an OPEN crossing you believe is a false
+positive — or you simply want to leave a rationale for the human reviewer —
+append a self-explanation ("申辩") to it:
+
+```
+lumo crossing explain <id> --note "this was a generated fixture, not a hand-edited migration"
+```
+
+This is the **inverse** of dispositioning, but it is the agent/CLI path
+(bearer-only; a clerk/human caller is refused) and it can **only append** an
+append-only note — it **never clears the crossing or unblocks Done**
+(disposition stays web + human-only, LUM-448). The note is shown to the human
+reviewer at disposition time, kept for later review, and explicitly labeled
+_agent self-report · unverified_. `<id>` must be a crossing on the
+**session-bound task** (resolved from `$CLAUDE_CODE_SESSION_ID`; cross-task
+targets and unbound/mismatched sessions are rejected). Earlier explanations are
+immutable — a correction is a new note.
+
 ### --json contract
 
 `--json` emits the full read model with a top-level `version` field

package/dist/cli/src/commands/crossing-explain.js

@@ -0,0 +1,93 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.crossingExplain = crossingExplain;
+const config_1 = require("../lib/config");
+const api_1 = require("../lib/api");
+const sanitize_1 = require("../lib/sanitize");
+/**
+ * `lumo crossing explain <id> --note "…"` — append an agent self-explanation
+ * ("申辩") to a boundary crossing (LUM-542).
+ *
+ * This is the AGENT side of the boundary-crossing review loop and the deliberate
+ * inverse of dispositioning: it can only ADD an append-only note for the human
+ * reviewer to weigh — it never clears the crossing or unblocks Done (a human
+ * dispositions that, in the web acceptance panel). The crossing must belong to
+ * the task this session is bound to; the binding is how the target task is
+ * resolved, so run it inside a session attached via `lumo session attach`.
+ */
+async function crossingExplain(crossingId, options = {}) {
+    if (!crossingId || crossingId.trim() === '') {
+        console.error('Error: a crossing id is required: lumo crossing explain <id> --note "…"');
+        return 1;
+    }
+    const note = options.note?.trim();
+    if (!note) {
+        console.error('Error: --note "<text>" is required (the explanation to record).');
+        return 1;
+    }
+    const creds = (0, config_1.readCredentials)();
+    if (!creds) {
+        console.error('Error: not logged in. Run `lumo auth login` first.');
+        return 1;
+    }
+    const base = (0, api_1.trimTrailingSlash)((0, api_1.resolveAuthedApiUrl)(creds.apiUrl));
+    const headers = {
+        Authorization: `Bearer ${creds.token}`,
+    };
+    const sessionId = process.env.CLAUDE_CODE_SESSION_ID;
+    if (sessionId)
+        headers['X-Lumo-Session-Id'] = sessionId;
+    // The crossing is addressed by id, but the route is task-scoped — resolve the
+    // bound task from the session so the server can verify the crossing is on it.
+    if (!sessionId) {
+        console.error('Error: $CLAUDE_CODE_SESSION_ID is not set — run inside a session bound via `lumo session attach <LUM-N>`.');
+        return 1;
+    }
+    let bound;
+    try {
+        const res = await fetch(`${base}/api/sessions/${encodeURIComponent(sessionId)}`, { headers });
+        bound = res.ok
+            ? (await res.json())
+            : null;
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        console.error(`Error: could not reach Lumo API (${msg})`);
+        return 1;
+    }
+    if (!bound?.taskIdentifier) {
+        console.error('Error: this session is not bound to a task. Run `lumo session attach <LUM-N>` first.');
+        return 1;
+    }
+    const taskId = bound.taskIdentifier;
+    let res;
+    try {
+        res = await fetch(`${base}/api/tasks/${encodeURIComponent(taskId)}/boundary-crossings/${encodeURIComponent(crossingId)}/explain`, {
+            method: 'POST',
+            headers: { ...headers, 'Content-Type': 'application/json' },
+            body: JSON.stringify({ note }),
+        });
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        console.error(`Error: could not reach Lumo API (${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 errBody = (await res.json().catch(() => null));
+        const detail = errBody && typeof errBody.error === 'string'
+            ? (0, sanitize_1.sanitizeField)(errBody.error)
+            : '';
+        console.error(`Error: explanation rejected (HTTP ${res.status})${detail ? ` — ${detail}` : ''}`);
+        return 1;
+    }
+    const outcome = (await res.json());
+    process.stdout.write(`✓ Recorded an explanation on crossing ${(0, sanitize_1.sanitizeField)(outcome.crossingId)}.\n` +
+        '  This is an append-only note for the human reviewer — it does not clear ' +
+        'the crossing or unblock Done.\n');
+    return;
+}

package/dist/cli/src/commands/memory-push.js

@@ -0,0 +1,93 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.memoryPush = memoryPush;
+const node_fs_1 = require("node:fs");
+const config_1 = require("../lib/config");
+const api_1 = require("../lib/api");
+const sanitize_1 = require("../lib/sanitize");
+const resolve_1 = require("../lib/resolve");
+const resolve_bound_task_1 = require("../lib/resolve-bound-task");
+const resolve_project_1 = require("../lib/resolve-project");
+const claude_memory_dir_1 = require("../lib/claude-memory-dir");
+const upsync_1 = require("../lib/upsync");
+/**
+ * `lumo memory push` — upsync (P3): promote locally-authored memories
+ * (`<memory-dir>/outbox/*.json`, each `{ category, content }`) to the team. Each
+ * is POSTed to the **existing** create-project-memory endpoint, so it goes
+ * through the same canonicalize → dedup → reconcile-on-write pipeline (LUM-538)
+ * as `lumo project memory add` — no parallel upsync path. Pushed files are
+ * removed from the outbox on success.
+ */
+async function memoryPush(options) {
+    const dir = (0, claude_memory_dir_1.resolveMemoryDir)(process.cwd(), undefined, options.dir);
+    const candidates = (0, upsync_1.collectUpsyncCandidates)(dir);
+    if (candidates.length === 0) {
+        console.log(`No upsync candidates in ${dir}/outbox — drop {category, content} JSON files there to promote them.`);
+        return;
+    }
+    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 projectId;
+    if (options.project) {
+        projectId = await (0, resolve_1.resolveProjectId)(base, creds.token, options.project);
+    }
+    else {
+        const bound = await (0, resolve_bound_task_1.resolveBoundTaskIdentifier)(apiUrl, creds.token);
+        if (!bound) {
+            console.error('Error: no --project given and no task bound to this session.\nPass --project <ref>, or run `lumo session attach <LUM-N>`.');
+            return 1;
+        }
+        const r = await (0, resolve_project_1.resolveBoundProjectId)(apiUrl, creds.token, bound);
+        if (!r.ok) {
+            console.error(`Error: ${r.error}`);
+            return 1;
+        }
+        projectId = r.id;
+    }
+    if (options.dryRun) {
+        console.log((0, sanitize_1.sanitizeField)(`[dry-run] would push ${candidates.length} memory(ies) to project ${projectId} via the existing create-project-memory pipeline`));
+        for (const c of candidates) {
+            console.log((0, sanitize_1.sanitizeField)(`  - ${c.category}: ${c.file}`));
+        }
+        return;
+    }
+    const url = (0, upsync_1.projectMemoriesEndpoint)(base, projectId);
+    let pushed = 0;
+    for (const c of candidates) {
+        let res;
+        try {
+            res = await fetch(url, {
+                method: 'POST',
+                headers: {
+                    Authorization: `Bearer ${creds.token}`,
+                    'Content-Type': 'application/json',
+                },
+                body: JSON.stringify({ category: c.category, content: c.content }),
+            });
+        }
+        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.ok) {
+            console.error((0, sanitize_1.sanitizeField)(`✗ ${c.file}: push failed (HTTP ${res.status})`));
+            continue;
+        }
+        try {
+            (0, node_fs_1.unlinkSync)(c.file);
+        }
+        catch {
+            // best-effort cleanup; a re-push is idempotent via reconcile-on-write
+        }
+        pushed++;
+        const body = (await res.json().catch(() => ({})));
+        console.log((0, sanitize_1.sanitizeField)(`✓ ${c.category} → ${body.outcome ?? 'pushed'} (${c.file})`));
+    }
+    console.log((0, sanitize_1.sanitizeField)(`Pushed ${pushed}/${candidates.length} to the team.`));
+}

package/dist/cli/src/commands/memory-sync.js

@@ -0,0 +1,104 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.memorySync = memorySync;
+const config_1 = require("../lib/config");
+const api_1 = require("../lib/api");
+const sanitize_1 = require("../lib/sanitize");
+const resolve_1 = require("../lib/resolve");
+const resolve_bound_task_1 = require("../lib/resolve-bound-task");
+const resolve_project_1 = require("../lib/resolve-project");
+const claude_memory_dir_1 = require("../lib/claude-memory-dir");
+const apply_sync_1 = require("../lib/apply-sync");
+const anchor_staleness_1 = require("../lib/anchor-staleness");
+/**
+ * `lumo memory sync` — downsync team memory into the local Claude Code memory
+ * store (`~/.claude/projects/<enc>/memory/team/*.md` + a managed MEMORY.md
+ * block). Runs alongside session-start injection (retiring injection is
+ * LUM-540). Only ever touches files it owns; dev-authored memory is never
+ * clobbered. `--dry-run` prints the plan; `--clean` removes everything sync owns.
+ */
+async function memorySync(options) {
+    const dir = (0, claude_memory_dir_1.resolveMemoryDir)(process.cwd(), undefined, options.dir);
+    // --clean is purely local — no project, no network, no login required.
+    if (options.clean) {
+        const summary = (0, apply_sync_1.applySync)(dir, { projectId: '', entries: [] }, { clean: true, dryRun: options.dryRun });
+        console.log((0, sanitize_1.sanitizeField)(`${options.dryRun ? '[dry-run] ' : ''}cleaned ${summary.removed.length} team memory file(s) from ${dir}`));
+        return;
+    }
+    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 projectId;
+    if (options.project) {
+        projectId = await (0, resolve_1.resolveProjectId)(base, creds.token, options.project);
+    }
+    else {
+        const bound = await (0, resolve_bound_task_1.resolveBoundTaskIdentifier)(apiUrl, creds.token);
+        if (!bound) {
+            console.error('Error: no --project given and no task bound to this session.\nPass --project <ref>, or run `lumo session attach <LUM-N>`.');
+            return 1;
+        }
+        const r = await (0, resolve_project_1.resolveBoundProjectId)(apiUrl, creds.token, bound);
+        if (!r.ok) {
+            console.error(`Error: ${r.error}`);
+            return 1;
+        }
+        projectId = r.id;
+    }
+    let res;
+    try {
+        res = await fetch(`${base}/api/projects/${encodeURIComponent(projectId)}/memories/sync-bundle`, { 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) {
+        console.error(`Error: memory sync failed (HTTP ${res.status})`);
+        return 1;
+    }
+    const { bundle } = (await res.json());
+    const summary = (0, apply_sync_1.applySync)(dir, bundle, { dryRun: options.dryRun });
+    const prefix = options.dryRun ? '[dry-run] ' : '';
+    console.log((0, sanitize_1.sanitizeField)(`${prefix}memory sync → ${dir}`));
+    console.log((0, sanitize_1.sanitizeField)(`${prefix}+${summary.added.length} added · ~${summary.updated.length} updated · -${summary.removed.length} removed` +
+        (summary.skippedDrift.length
+            ? ` · ⚠ ${summary.skippedDrift.length} drift-skipped (locally edited)`
+            : '')));
+    if (summary.skippedDrift.length) {
+        console.log((0, sanitize_1.sanitizeField)(`  drift-skipped: ${summary.skippedDrift.join(', ')} — local edits preserved (upsync candidates)`));
+    }
+    // Code-anchor staleness (LUM-547): now that the team memory is local, check
+    // each memory's code anchors against this repo and report stale candidates to
+    // the server (feeds the P4a retire pool; never archives — human confirms).
+    // Best-effort: a detection/report failure never fails the sync.
+    if ((0, anchor_staleness_1.shouldRunAnchorCheck)(options)) {
+        try {
+            const { candidates, report } = await (0, anchor_staleness_1.runAnchorCheck)({
+                cwd: process.cwd(),
+                base,
+                token: creds.token,
+                projectId,
+                entries: bundle.entries,
+            });
+            if (candidates.length > 0 && report.ok) {
+                console.log((0, sanitize_1.sanitizeField)(`anchor check → ${candidates.length} stale-anchor candidate(s) reported for human review`));
+            }
+            else if (candidates.length > 0 && !report.ok) {
+                console.log((0, sanitize_1.sanitizeField)(`anchor check → found ${candidates.length} stale candidate(s) but reporting failed (HTTP ${report.status ?? '?'})`));
+            }
+        }
+        catch {
+            // detection is advisory — swallow and leave the sync result intact.
+        }
+    }
+}