@lumoai/cli 1.46.0 → 1.48.0

package/assets/skill/references/tasks.md

@@ -99,18 +99,18 @@ The `Tags:` line is omitted when the resulting tag set is empty.
 
 The server's transition matrix (`lib/task/state-machine.ts`):
 
-| From        | Allowed targets                                     |
-| ----------- | --------------------------------------------------- |
-| TODO        | IN_PROGRESS, IN_REVIEW, DONE                        |
-| IN_PROGRESS | TODO, IN_REVIEW, DONE                               |
-| IN_REVIEW   | TODO, IN_PROGRESS, DONE                             |
-| DONE        | TODO, IN_PROGRESS (reopen only — **not** IN_REVIEW) |
+| From        | Allowed targets                       |
+| ----------- | ------------------------------------- |
+| TODO        | IN_PROGRESS, IN_REVIEW, DONE          |
+| IN_PROGRESS | TODO, IN_REVIEW, DONE                 |
+| IN_REVIEW   | TODO, IN_PROGRESS, DONE               |
+| DONE        | TODO, IN_PROGRESS, IN_REVIEW (reopen) |
 
 Practical rules:
 
-- **One call suffices.** `--status done` straight from TODO or IN_PROGRESS is legal — never walk `in_progress → in_review → done` as a ritual (measured in LUM-392: 70 such chains wasted ~75 calls).
+- **One call suffices.** `--status done` straight from TODO or IN_PROGRESS is legal — never walk `in_progress → in_review → done` as a ritual; it just wastes calls.
 - **Under the verify flow you don't set `in_review`/`done` at all** — `lumo verify` moves the task to IN_REVIEW on all-pass and the DONE adjudication is human-only.
-- **DONE → IN_REVIEW is rejected (409).** To attach follow-up context to a DONE task, use `lumo task comment` instead of reopening.
+- **A DONE task can be reopened** — to IN_REVIEW, IN_PROGRESS, or TODO. Reopening is a plain status change and does not alter any recorded acceptance verdict; verdict adjudication is human-only and has no CLI path. To attach context without reopening, `lumo task comment` works.
 
 ### When to suggest `task update`
 

package/assets/skill/references/verify.md

@@ -1,7 +1,6 @@
 # lumo verify — machine verification loop
 
-`lumo verify` is the machine half of the acceptance system (Acceptance v1,
-LUM-343): it executes every **MACHINE** criterion's checkpointer in the local
+`lumo verify` is the machine half of the acceptance system: it executes every **MACHINE** criterion's checkpointer in the local
 repo, POSTs one structured PASS/FAIL verdict per criterion, and prints what to
 do next. Execution is on the client; adjudication is server-side — round
 numbering, the **3-round cap**, escalation, and the **IN_REVIEW** transition all
@@ -14,11 +13,22 @@ touching its status — run `lumo verify`.** The loop replaces "I read the code
 and it looks done" with executed evidence.
 
 ```bash
-lumo verify                 # session-bound task
-lumo verify LUM-42          # explicit task (overrides the session binding)
-lumo verify --timeout 900   # per-checkpointer timeout in seconds (default 600)
+lumo verify --note "implemented X in foo.ts because Y; tests + tsc pass"   # session-bound task
+lumo verify LUM-42 --note "…"            # explicit task (overrides the session binding)
+lumo verify --note "…" --timeout 900     # per-checkpointer timeout in seconds (default 600)
 ```
 
+**`--note` is required (LUM-597)** whenever a round will actually be posted (the
+task has MACHINE criteria). It is your one-line self-report — what you did and
+why it is ready ("我改了 X,因为 Y 可验收"). When the round all-passes and the
+task flips to IN_REVIEW, the note is frozen as the task's **claim** (provenance
+`AGENT` — the汇报者's own voice, not a summarizer paraphrase) and is checked
+against the diff for faithfulness. Capturing the claim is deterministic ("不填不
+让 post"); whether it is _truthful_ is the faithfulness audit's job — so don't
+under- or over-state it. A missing/blank note is refused **before** the round is
+posted, so no round is burned; just re-run with one. (An old CLI that omits it
+still verifies — the claim degrades to the synthesized run-summary fallback.)
+
 ## What one round does
 
 1. Loads the task's acceptance contract and picks out MACHINE criteria.
@@ -29,11 +39,11 @@ lumo verify --timeout 900   # per-checkpointer timeout in seconds (default 600)
    TaskActivity event.
 4. Prints the round outcome:
 
-| Round outcome             | Effect                                                                                                                      | What to do                                                                                    |
-| ------------------------- | --------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- |
-| **All PASS**              | Task transitions to **IN_REVIEW** (existing state machine + TASK_IN_REVIEW notification)                                    | **Stop here.** Human adjudication + any HUMAN criteria take over; **never set DONE yourself** |
-| **Any FAIL**              | Task status untouched; unmet criteria printed as next actions (statement, checkpointer, failure tail)                       | Fix and re-run                                                                                |
-| **Round 3 still failing** | Loop escalates: a human is notified (AGENT_VERIFY, requires action); further `lumo verify` rounds are rejected with **409** | **Stop retrying**; fix only what the human directs                                            |
+| Round outcome             | Effect                                                                                                                                                            | What to do                                                                                    |
+| ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- |
+| **All PASS**              | Task transitions to **IN_REVIEW** (existing state machine + TASK_IN_REVIEW notification); the `--note` self-report is frozen as the task's claim (source `AGENT`) | **Stop here.** Human adjudication + any HUMAN criteria take over; **never set DONE yourself** |
+| **Any FAIL**              | Task status untouched; unmet criteria printed as next actions (statement, checkpointer, failure tail)                                                             | Fix and re-run                                                                                |
+| **Round 3 still failing** | Loop escalates: a human is notified (AGENT_VERIFY, requires action); further `lumo verify` rounds are rejected with **409**                                       | **Stop retrying**; fix only what the human directs                                            |
 
 Exit code 0 = all passed (or nothing to run); 1 = failures, escalation, or
 errors.
@@ -57,7 +67,7 @@ errors.
 | **HUMAN-only contract** (zero MACHINE criteria) | Nothing to run; CLI says so and suggests `lumo task update <id> --status in_review` for human review. No server write happens.                                                                                                                                                                                       |
 | **Partial round**                               | A round must cover every MACHINE criterion; the CLI always runs all of them and the server rejects partial rounds.                                                                                                                                                                                                   |
 | **`REVIEW_ADDED` criteria**                     | Criteria added during review appear in the contract and are picked up automatically by the next round.                                                                                                                                                                                                               |
-| **Session bound to a different task** (LUM-459) | Server returns 409, surfaced as an error. No advisory printed; the verify round is rejected outright.                                                                                                                                                                                                                |
+| **Session bound to a different task**           | Server returns 409, surfaced as an error. No advisory printed; the verify round is rejected outright.                                                                                                                                                                                                                |
 | **Provably-unbound session**                    | Response carries `bindingAdvisory: 'unbound'`; prints `⚠ Working unbound — this verify ran from a Claude Code session not attached to the task.` Recorded as a `SESSION_BINDING_MISSING` boundary crossing (visible in `lumo task status` open crossings). Run `lumo session attach <LUM-N>` before the next verify. |
 | **Unconfirmed session binding**                 | `bindingAdvisory: 'unconfirmed'` → softer advisory `⚠ Could not confirm this session is attached to the task.` Same remediation: `lumo session attach <LUM-N>`.                                                                                                                                                      |
 
@@ -85,8 +95,7 @@ clauses that can never be found wanting.
 
 ## lumo task status — the read half (self-check entry point)
 
-`lumo task status [task] [--json]` is the read-only counterpart of the loop
-(LUM-344): pure read, milliseconds, no LLM, never writes — running it costs
+`lumo task status [task] [--json]` is the read-only counterpart of the loop: pure read, milliseconds, no LLM, never writes — running it costs
 nothing and burns no round. Defaults to the session-bound task; an explicit
 identifier overrides.
 
@@ -111,34 +120,35 @@ what's unmet and why (the exact failure tails), and how many rounds are left.
 ### What it prints
 
 - **Header** — task identifier/title/status + `verification round N/3` (round 0 = never verified) + an escalation warning when the machine loop is exhausted.
-- **Claim vs verification** (LUM-564) — 规律 2 声称vs核验: the headline contrast, printed right after the header (whenever the contract exists), so the report shows **both** columns instead of only the verification one. Two sides:
-  - **Claim** — what the agent _says_ it did: the latest session's run summary, **same-source** with the web delivery card's `latestRunSummary` (the LLM run summary, else the raw STOP turn digest). Explicitly tagged an **unverified self-report** (`agent self-report · estimated, not verification`) — estimate-tier provenance (估, not 测), with a `↳ source:` line distinguishing an `LLM run summary` from a `raw turn digest — no LLM summary yet`. **Fail-closed**: with no run summary it prints `not generated yet — the agent run summary is synthesized when the task reaches DONE`, never a fabricated claim.
-  - **Verification** — what was actually _confirmed_ (measured): the machine-verification rollup (LUM-470/456) `N machine-verified / M human override (of T MACHINE criteria)` over the active MACHINE criteria (relocated here from its old standalone line under `Criteria`), plus `X of Y criteria met by their latest verdict`. **Fail-closed**: before any round runs it prints `no verification has run yet — the claim is unconfirmed` rather than implying a pass.
-  - Carried in `--json` as `claim { text, source }` (`source: 'RUN_SUMMARY' | 'DIGEST' | null`; `text: null` = none generated). Omitted only against an older server that doesn't emit the field. The machine-verification rollup is still carried top-level as `machineVerification`.
+- **Claim vs verification** — 规律 2 声称vs核验: the headline contrast, printed right after the header (whenever the contract exists), so the report shows **both** columns instead of only the verification one. Two sides:
+  - **Claim** — what the agent _says_ it did: an **unverified self-report** (`agent self-report · estimated, not verification`), estimate-tier provenance (估, not 测). Sourced by layering (LUM-597, preference `AGENT > RUN_SUMMARY > DIGEST > null`): if you supplied a `lumo verify --note`, that **own self-report** is the claim (`↳ source: agent self-report (verify --note)`) — the汇报者's voice, what faithfulness judges. Absent a self-report (old CLI / non-verify path) it degrades to the summarizer paraphrase, labelled honestly (`↳ source: synthesized run summary (no self-report)`). **Fail-closed**: when only a raw STOP turn digest exists it prints `generating — the formal run summary is still being synthesized` and **withholds the raw digest**; with no material at all it prints `not generated yet — …`, never a fabricated claim.
+  - **Verification** — what was actually _confirmed_ (measured): the machine-verification rollup `N machine-verified / M human override (of T MACHINE criteria)` over the active MACHINE criteria (relocated here from its old standalone line under `Criteria`), plus `X of Y criteria met by their latest verdict`. **Fail-closed**: before any round runs it prints `no verification has run yet — the claim is unconfirmed` rather than implying a pass.
+  - **Faithfulness** — the third state over the two columns: whether the CLAIM itself is _true_, read from the persisted faithfulness verdict (no LLM at read time), printed as `▸ Faithfulness — does the claim match the delivery`. One of `faithful` / `overstated` (claim says more than the diff/PR shows) / `under-reported` (claim says less) / `unjudgeable`, with an `· evidence: PR #N · <sha>` pointer when the judge cited one. **Fail-closed**: `not yet judged` (no verdict — distinct from a real `unjudgeable` verdict) and `… (stale — re-checked on the next batch)` (judged against an older claim snapshot, the verdict still shown) are surfaced explicitly. Omitted only against an older server that doesn't emit it.
+  - Carried in `--json` as `claim { text, source }` (`source: 'AGENT' | 'RUN_SUMMARY' | 'DIGEST' | null`; `AGENT` = the verify self-report, `RUN_SUMMARY`/`DIGEST` = the synthesized fallback; `text: null` = none generated) and `faithfulness { state, verdict, evidence, diffShas, prNumbers, judgedAt, judgedClaimAt }` (`state` adds `PENDING`/`STALE` over the four verdicts). Omitted only against an older server that doesn't emit the field. The machine-verification rollup is still carried top-level as `machineVerification`.
 - **Criteria** — every criterion as `<glyph> <id>  [TYPE]  SOURCE@rN statement` (✓ latest verdict passed / ✗ failed / ○ no verdict yet) with its checkpointer and latest verdict line (failure tail on fail). `REVIEW_ADDED@rN` provenance is visible per row.
-  - A passing **MACHINE** criterion's verdict line carries a machine-state tag derived from the read model's `machinePassed` flag, NOT the latest verdict (LUM-470): `· machine-verified` when a checkpointer actually passed it (even after a human later signs the task off), or `· human override (no machine pass)` when it passes only on a human sign-off with no machine run underneath. This keeps the terminal honest with web — a machine-verified criterion that a human co-signed no longer reads as a plain human pass.
-  - A verdict's **evidence is drillable** (LUM-563), rendered as an indented `↳ evidence:` line under the verdict (PASS _and_ FAIL) instead of the inert raw pointer that used to ride the verdict line — so a conclusion points at real proof you can act on, not just the `check:` command: a `cmd:` pointer prints the actual command + exit code (`ran \`…\` → exit N · re-run to reproduce`), a `file:`pointer prints a terminal-clickable`path:line`, and a `commit:` pointer prints a navigable web URL (`<repo>/commit/<hash>`, resolved from the local git `origin`remote) or a`git show <hash>`fallback when no remote resolves. A criterion that **requires evidence but has none recorded yet** (e.g. a HUMAN evidence criterion before sign-off) renders an explicit`↳ evidence: pending — no reference recorded yet`(fail-closed) instead of a bare, dead`[evidence]` tag.
-  - A pass can carry a **`⚠ pre-edit version`** note (LUM-457): the criterion was changed after that verdict (reworded, or its checkpointer was swapped so the recorded evidence ran a different command). The pass still counts as met (a stale pass does not block DONE — render-only signal), but it vouches for an older version — **re-run `lumo verify` to re-confirm against the current criterion.** This is the habit whenever you edit a MACHINE criterion's checkpointer mid-task: change the check, then re-verify so the green is honest.
+  - A passing **MACHINE** criterion's verdict line carries a machine-state tag derived from the read model's `machinePassed` flag, NOT the latest verdict: `· machine-verified` when a checkpointer actually passed it (even after a human later signs the task off), or `· human override (no machine pass)` when it passes only on a human sign-off with no machine run underneath. This keeps the terminal honest with web — a machine-verified criterion that a human co-signed no longer reads as a plain human pass.
+  - A verdict's **evidence is drillable**, rendered as an indented `↳ evidence:` line under the verdict (PASS _and_ FAIL) instead of the inert raw pointer that used to ride the verdict line — so a conclusion points at real proof you can act on, not just the `check:` command: a `cmd:` pointer prints the actual command + exit code (`ran \`…\` → exit N · re-run to reproduce`), a `file:`pointer prints a terminal-clickable`path:line`, and a `commit:` pointer prints a navigable web URL (`<repo>/commit/<hash>`, resolved from the local git `origin`remote) or a`git show <hash>`fallback when no remote resolves. A criterion that **requires evidence but has none recorded yet** (e.g. a HUMAN evidence criterion before sign-off) renders an explicit`↳ evidence: pending — no reference recorded yet`(fail-closed) instead of a bare, dead`[evidence]` tag.
+  - A pass can carry a **`⚠ pre-edit version`** note: the criterion was changed after that verdict (reworded, or its checkpointer was swapped so the recorded evidence ran a different command). The pass still counts as met (a stale pass does not block DONE — render-only signal), but it vouches for an older version — **re-run `lumo verify` to re-confirm against the current criterion.** This is the habit whenever you edit a MACHINE criterion's checkpointer mid-task: change the check, then re-verify so the green is honest.
 - **History** — one line per recorded round: `rN · timestamp · X PASS / Y FAIL`.
 - **Last round failures** — the most recent round's FAIL verdicts with their rejection reasons (why the last round bounced).
-- **Cost** (LUM-560) — 规律 1: the costs a human should weigh, on the same report as the verdict instead of scattered across the web delivery card and `task lineage`. Three lines: **Tokens** (total input+output+cache across the task's sessions), **Active time** (non-idle agent seconds — Σ per-turn `STOP − prompt`, LUM-487), and **Rework rounds** (verify rounds that recorded a FAIL). Read from the **same** server-side source the web delivery card consumes (`retrospectiveRepository.loadActuals`), so the two reports cannot drift. Token cost is **fail-closed**: when no session usage was recorded it prints `Tokens: not recorded (no session usage captured)`, kept distinct from a measured `0` (没测到 vs 花了0, aligned with LUM-559). Carried in `--json` as `cost { tokenCost, activeTimeSec, reworkRounds }` (`tokenCost: null` = not measured). Omitted only against an older server that doesn't emit the field.
-- **Struggle / rework / outstanding** (LUM-561) — the anti-mum-and-deaf block: **always printed when the contract exists, even on a clean 0-unmet task** so a passing task still shows its scars instead of wiping them to a single PASS count. Lists, when present:
+- **Cost** — 规律 1: the costs a human should weigh, on the same report as the verdict instead of scattered across the web delivery card and `task lineage`. Three lines: **Tokens** (total input+output+cache across the task's sessions), **Active time** (non-idle agent seconds — Σ per-turn `STOP − prompt`), and **Rework rounds** (verify rounds that recorded a FAIL). Read from the **same** server-side source the web delivery card consumes (`retrospectiveRepository.loadActuals`), so the two reports cannot drift. Token cost is **fail-closed**: when no session usage was recorded it prints `Tokens: not recorded (no session usage captured)`, kept distinct from a measured `0` (没测到 vs 花了0). Carried in `--json` as `cost { tokenCost, activeTimeSec, reworkRounds }` (`tokenCost: null` = not measured). Omitted only against an older server that doesn't emit the field.
+- **Struggle / rework / outstanding** — the anti-mum-and-deaf block: **always printed when the contract exists, even on a clean 0-unmet task** so a passing task still shows its scars instead of wiping them to a single PASS count. Lists, when present:
   - **rework rounds** — verify rounds that had a FAIL;
   - **send-backs** — criteria sent back by a human/agent verdict (a MACHINE verify-loop FAIL is not a 打回), with their open/resolved lifecycle, preserved even for since-removed criteria;
   - **leftover follow-ups** — criteria whose latest verdict is `PASS_WITH_FOLLOWUP`;
-  - **PR iterations** — when the task has >1 PR (the dominant rework signal when the verify loop ran once but the work churned across many follow-up PRs — e.g. LUM-557: ~10 PRs vs 1 verify round); a single PR is the happy path and is not flagged;
+  - **PR iterations** — when the task has >1 PR (the dominant rework signal when the verify loop ran once but the work churned across many follow-up PRs); a single PR is the happy path and is not flagged;
   - **reopens** — backward `IN_REVIEW/DONE → IN_PROGRESS/TODO` transitions (from the `STATUS_CHANGED` log): the task reached review/done and got bounced, a rework that leaves no FAIL verdict.
 
   When the trail is genuinely empty it states the **basis** (`None recorded — N rounds run, 0 FAIL, no send-backs, no reopens, no leftover follow-ups`); when nothing has been verified yet it says so (`No verification has run yet — cannot confirm there were no difficulties`) rather than rendering an implicitly-clean slate. Carried in `--json` as `struggleTrail` (incl. `pullRequests` + `reopens`).
 
-- **Trend** (LUM-562) — 规律 7 趋势非快照: the _movement_ of the key quantities across the task's attempts, not a single snapshot. Where History/Cost/Struggle list current values, this shows direction: **Pass rate** across verification rounds (`r1 60% → r2 100% (↑ +40pts)`), **Cost/session** across the task's sessions (`4.2K → 1.1K tokens (↓), 5.3K total` — per-session spend from the same source as the **Cost** total, so the trajectory's points sum to it), and **Rework** accrual (`3 accrued — 1 FAIL round, 1 reopen, +1 PR cycle (↑ from 0)`). **Honest about a single point:** with only one round and one session every quantity is one data point, so it prints `Single attempt so far — no trajectory yet (a trend needs ≥2 rounds or sessions)` rather than drawing a fake arrow off one value (closes the named "1-round pass = single point" gap). When nothing was verified and no cost was measured it says `No verification rounds or measured cost yet — nothing to trend`. Carried in `--json` as `trend { passRate[], cost[], rework{} }`. Omitted only against an older server.
+- **Trend** — 规律 7 趋势非快照: the _movement_ of the key quantities across the task's attempts, not a single snapshot. Where History/Cost/Struggle list current values, this shows direction: **Pass rate** across verification rounds (`r1 60% → r2 100% (↑ +40pts)`), **Cost/session** across the task's sessions (`4.2K → 1.1K tokens (↓), 5.3K total` — per-session spend from the same source as the **Cost** total, so the trajectory's points sum to it), and **Rework** accrual (`3 accrued — 1 FAIL round, 1 reopen, +1 PR cycle (↑ from 0)`). **Honest about a single point:** with only one round and one session every quantity is one data point, so it prints `Single attempt so far — no trajectory yet (a trend needs ≥2 rounds or sessions)` rather than drawing a fake arrow off one value. When nothing was verified and no cost was measured it says `No verification rounds or measured cost yet — nothing to trend`. Carried in `--json` as `trend { passRate[], cost[], rework{} }`. Omitted only against an older server.
 
 - **Next actions** — the unmet criteria (latest verdict is not a pass: failed or never verified, HUMAN ones included). This list IS the plan — recomputed from the event log on every read, never maintained separately. Empty + rounds recorded = awaiting human adjudication.
-- **Open boundary crossings** (LUM-448) — a trailing safety block when the task has ≥1 OPEN (undispositioned) forbidden-action crossing: a count, then one line per crossing `• [SEVERITY] CATEGORY — <clipped detail>` (highest-severity first), each followed by a read-only **attribution** line `↳ by model=<m> · agent=<type>[/branch] · session=<8-char prefix>` (LUM-469 — who/what crossed; any dimension that couldn't be resolved server-side prints `unknown`, never a fabricated value), then a pointer to the web acceptance panel. Silent when there are none, so it never overshadows the criteria.
-  - **Read-only awareness** — this surfaces crossings detected elsewhere (LUM-426/435/442); there is no CLI path to disposition or clear one. Disposition stays web + human-only (LUM-426/435/422): an agent/CLI bearer cannot clear its own crossing from the terminal.
-  - **The check fails closed (LUM-480):** if the crossings read itself errors (network / server / parse), the block prints `⚠ Boundary-crossing check failed (network/server error) — 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".
+- **Open boundary crossings** — a trailing safety block when the task has ≥1 OPEN (undispositioned) forbidden-action crossing: a count, then one line per crossing `• [SEVERITY] CATEGORY — <clipped detail>` (highest-severity first), each followed by a read-only **attribution** line `↳ by model=<m> · agent=<type>[/branch] · session=<8-char prefix>` (who/what crossed; any dimension that couldn't be resolved server-side prints `unknown`, never a fabricated value), then a pointer to the web acceptance panel. Silent when there are none, so it never overshadows the criteria.
+  - **Read-only awareness** — this surfaces crossings detected elsewhere; there is no CLI path to disposition or clear one. Disposition stays web + human-only: an agent/CLI bearer cannot clear its own crossing from the terminal.
+  - **The check fails closed:** if the crossings read itself errors (network / server / parse), the block prints `⚠ Boundary-crossing check failed (network/server error) — 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)
+### Responding to an open crossing — `lumo crossing explain`
 
 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
@@ -151,7 +161,7 @@ lumo crossing explain <id> --note "this was a generated fixture, not a hand-edit
 This is the **inverse** of dispositioning, but it is the agent/CLI path
 (bearer-only; a clerk/human caller is refused). Behavior:
 
-- it can **only append** an append-only note — it **never clears the crossing or unblocks Done** (disposition stays web + human-only, LUM-448);
+- it can **only append** an append-only note — it **never clears the crossing or unblocks Done** (disposition stays web + human-only);
 - 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.
@@ -162,16 +172,16 @@ This is the **inverse** of dispositioning, but it is the agent/CLI path
 `1`). The schema is versioned: breaking shape changes bump the major; additive
 fields don't. Pin on `version` when scripting against it.
 
-- each criterion carries `machinePassed` (boolean — a checkpointer currently vouches for it; LUM-456/470);
+- each criterion carries `machinePassed` (boolean — a checkpointer currently vouches for it);
 - the payload carries a top-level `machineVerification` aggregate `{ total, machineVerified, humanOverridden }` over the active MACHINE criteria — read these, not `latestVerdict` alone, to tell a machine-verified criterion from a human override;
-- open boundary crossings ride along as an additive top-level `openCrossings`, each entry `{ id, category, severity, detail, attribution }` where `attribution` is `{ workspaceMemberId, sessionId, agent, worktreeBranch, model }` with every field nullable — null = unknown, never fabricated (LUM-469); the array length is the count. Same read-only awareness, no write path;
-- **`openCrossings` is `null` when the crossings check failed (LUM-480)** — distinct from `[]` (a successful read with zero open crossings). Script consumers must treat `null` as "unknown / could not confirm", **not** "safe".
+- open boundary crossings ride along as an additive top-level `openCrossings`, each entry `{ id, category, severity, detail, attribution }` where `attribution` is `{ workspaceMemberId, sessionId, agent, worktreeBranch, model }` with every field nullable — null = unknown, never fabricated; the array length is the count. Same read-only awareness, no write path;
+- **`openCrossings` is `null` when the crossings check failed** — distinct from `[]` (a successful read with zero open crossings). Script consumers must treat `null` as "unknown / could not confirm", **not** "safe".
 
 `status` reads; `verify` judges. Running status never starts a round, never
 escalates, and never changes task state — loop rules (cap 3, IN_REVIEW on
 all-pass, human-only DONE) live entirely in `lumo verify` and the server.
 
-## lumo verdict — the three verdict channels (LUM-422)
+## lumo verdict — the three verdict channels
 
 `lumo verify` is the MACHINE channel. `lumo verdict` covers the other two — the
 HUMAN pass and the AGENT send-back — under one red line: **no passing data row is

package/assets/skill/references/worktree.md

@@ -36,7 +36,7 @@ Errors if the target dir already exists; reuses the branch if it already exists
 
 - **`prisma generate` clobbers all worktrees.** The generated client lives in the shared (symlinked) `node_modules`, so a `generate` in one worktree overwrites the client every parallel worktree depends on. Verify with jest (SWC mocks Prisma); do `generate + tsc` atomically once at the end.
 - **Run jest from the worktree root** (`cd` in first). `cli/` has no jest config; running from the main checkout hits the `cli/package.json` haste collision and silently runs the wrong tests.
-- **Husky hooks are copied in for you.** Husky owns hooks via `core.hooksPath = .husky/_`, resolved relative to each worktree's root. That `_` shim is **untracked** (regenerated on the main checkout's `npm install`/`prepare`), so a fresh worktree would lack it and git would **silently skip every hook** — pre-commit (lint-staged) and commit-msg (LUM-405 drift-check). With no GitHub CI, husky is the only deterministic quality gate, so `add` copies `.husky/_` in (copy, not symlink). If the main checkout has no `.husky/_`, `add` warns you to `npm install` there rather than skipping silently.
+- **Husky hooks are copied in for you.** Husky owns hooks via `core.hooksPath = .husky/_`, resolved relative to each worktree's root. That `_` shim is **untracked** (regenerated on the main checkout's `npm install`/`prepare`), so a fresh worktree would lack it and git would **silently skip every hook** — pre-commit (lint-staged) and commit-msg (drift-check). With no GitHub CI, husky is the only deterministic quality gate, so `add` copies `.husky/_` in (copy, not symlink). If the main checkout has no `.husky/_`, `add` warns you to `npm install` there rather than skipping silently.
 - **Never `npm install` / `npm ci` inside a worktree.** npm doesn't respect the `node_modules` symlink — it deletes it and reifies a full standalone tree (~1 min, shared prisma-client gone). Install only in the main checkout, then re-create the symlink if npm replaced it. (Older npm could plant a self-referential `node_modules/node_modules` that hard-panics Turbopack's `next build`; the `prebuild`/`predev`/`preanalyze` guard `scripts/fix-nodemodules-selflink.ts` removes it, but this rule avoids the mess.)
 
 ## `lumo worktree rm <LUM-N>`

package/dist/cli/src/commands/criteria-audit.js

@@ -0,0 +1,52 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.formatAuditReport = formatAuditReport;
+exports.criteriaAudit = criteriaAudit;
+const config_1 = require("../lib/config");
+const api_1 = require("../lib/api");
+const KIND_ORDER = [
+    'EXTERNAL_FACT',
+    'AGENT_CONSTRUCTED_STATE',
+    'PENDING_OUTCOME',
+    'UNVERIFIED_ASSERTION',
+    'UNCLASSIFIED',
+];
+function formatAuditReport(r) {
+    const lines = ['Criteria referent-kind audit (workspace)', ''];
+    for (const k of KIND_ORDER) {
+        const n = r.byEffectiveKind[k] ?? 0;
+        const pct = r.total === 0 ? 0 : Math.round((n / r.total) * 100);
+        lines.push(`  ${k.padEnd(24)} ${String(n).padStart(4)}  (${pct}%)`);
+    }
+    lines.push('');
+    const pct = Math.round(r.selfConfirmingGreenRatio * 100);
+    lines.push(`  self-confirming green: ${pct}% of ${r.classified} classified criteria`);
+    lines.push(`  (AGENT_CONSTRUCTED_STATE + UNVERIFIED_ASSERTION — green that confirms only the agent's own work)`);
+    return lines.join('\n') + '\n';
+}
+/** `lumo criteria audit` — workspace-level referent-kind distribution. */
+async function criteriaAudit() {
+    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));
+    let res;
+    try {
+        res = await fetch(`${base}/api/criteria/audit`, {
+            headers: { Authorization: `Bearer ${creds.token}` },
+        });
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        console.error(`Error: could not reach Lumo API (${msg})`);
+        return 1;
+    }
+    if (!res.ok) {
+        console.error(`Error: criteria audit failed (HTTP ${res.status})`);
+        return 1;
+    }
+    const report = (await res.json());
+    process.stdout.write(formatAuditReport(report));
+}

package/dist/cli/src/commands/outcome.js

@@ -0,0 +1,221 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.outcomeRecord = outcomeRecord;
+exports.outcomeShow = outcomeShow;
+exports.outcomeRate = outcomeRate;
+const config_1 = require("../lib/config");
+const api_1 = require("../lib/api");
+const sanitize_1 = require("../lib/sanitize");
+/**
+ * `lumo outcome` — the post-hoc outcome well (LUM-598).
+ *
+ * The well is the single external oracle for correctness + fidelity: it records
+ * the real-world fate a delivery met AFTER it shipped. It is a FALSIFIER, not a
+ * verifier — it only ever reads REJECTED (reality revoked/redid/bypassed the
+ * work) or INCONCLUSIVE (no rejection on record). There is deliberately no
+ * "mark satisfied": the absence of a rejection is not a pass.
+ */
+const MANUAL_KINDS = [
+    'REVERTED',
+    'ROLLED_BACK',
+    'CI_REGRESSION',
+    'DOWNSTREAM_REDIRECT',
+    'BYPASSED',
+    'MANUAL',
+];
+function authBase() {
+    const creds = (0, config_1.readCredentials)();
+    if (!creds)
+        return { error: 'not logged in. Run `lumo auth login` first.' };
+    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;
+    return { base, headers };
+}
+/**
+ * `lumo outcome record <task> --note "<what reality did>" [--kind <kind>]` —
+ * record a human-observed post-hoc REJECTION of a delivery. Append-only. The
+ * note is mandatory (the observed referent); the default kind is MANUAL.
+ */
+async function outcomeRecord(taskId, options = {}) {
+    if (!taskId || taskId.trim() === '') {
+        console.error('Error: a task is required: lumo outcome record <task> --note "…"');
+        return 1;
+    }
+    const note = options.note?.trim();
+    if (!note) {
+        console.error('Error: --note "<what reality did>" is required (the observed rejection, e.g. "reverted in #812 after prod incident").');
+        return 1;
+    }
+    const kind = (options.kind?.trim().toUpperCase() ||
+        'MANUAL');
+    if (!MANUAL_KINDS.includes(kind)) {
+        console.error(`Error: --kind must be one of: ${MANUAL_KINDS.map(k => k.toLowerCase()).join(', ')}`);
+        return 1;
+    }
+    const auth = authBase();
+    if ('error' in auth) {
+        console.error(`Error: ${auth.error}`);
+        return 1;
+    }
+    const payload = { kind, note };
+    if (options.occurredAt?.trim())
+        payload.occurredAt = options.occurredAt.trim();
+    let res;
+    try {
+        res = await fetch(`${auth.base}/api/tasks/${encodeURIComponent(taskId)}/outcome-signals`, {
+            method: 'POST',
+            headers: { ...auth.headers, 'Content-Type': 'application/json' },
+            body: JSON.stringify(payload),
+        });
+    }
+    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: outcome not recorded (HTTP ${res.status})${detail ? ` — ${detail}` : ''}`);
+        return 1;
+    }
+    process.stdout.write(`✓ Recorded a ${(0, sanitize_1.sanitizeField)(kind.toLowerCase())} rejection on ${(0, sanitize_1.sanitizeField)(taskId)}.\n` +
+        '  The well is a falsifier — this marks the delivery REJECTED by reality; ' +
+        'it is append-only and there is no "satisfied" counterpart.\n');
+    return;
+}
+/**
+ * `lumo outcome show <task>` — read the well for a task: the falsifier verdict
+ * plus its backing rejection signals.
+ */
+async function outcomeShow(taskId) {
+    if (!taskId || taskId.trim() === '') {
+        console.error('Error: a task is required: lumo outcome show <task>');
+        return 1;
+    }
+    const auth = authBase();
+    if ('error' in auth) {
+        console.error(`Error: ${auth.error}`);
+        return 1;
+    }
+    let res;
+    try {
+        res = await fetch(`${auth.base}/api/tasks/${encodeURIComponent(taskId)}/outcome-signals`, { headers: auth.headers });
+    }
+    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) {
+        console.error(`Error: could not read the well (HTTP ${res.status}).`);
+        return 1;
+    }
+    const well = (await res.json());
+    const mark = well.verdict === 'REJECTED' ? '✗' : '·';
+    process.stdout.write(`${mark} Outcome well — ${(0, sanitize_1.sanitizeField)(taskId)}: ${well.verdict}\n`);
+    if (well.verdict === 'INCONCLUSIVE') {
+        process.stdout.write('  No rejection on record. INCONCLUSIVE ≠ satisfied — the well only ' +
+            'asserts rejection; silence is not a pass.\n');
+        return;
+    }
+    for (const s of well.signals) {
+        const when = (s.occurredAt ?? s.detectedAt).slice(0, 10);
+        const note = s.evidence?.note ? ` — ${(0, sanitize_1.sanitizeField)(s.evidence.note)}` : '';
+        process.stdout.write(`  ${when}  ${(0, sanitize_1.sanitizeField)(s.kind)} (${(0, sanitize_1.sanitizeField)(s.source)})${note}\n`);
+    }
+    return;
+}
+/** Render the report client-side (same pattern as `lumo cost` / `outcome show`). */
+function formatRate(report) {
+    const lines = [];
+    lines.push('Trust × post-hoc fate — delivery-time forecast confidence vs the outcome well');
+    lines.push('  (rejection rate is a LOWER BOUND: the well only records rejections; ' +
+        'no signal = INCONCLUSIVE, never "satisfied")');
+    lines.push(`  ${report.totalDeliveries} snapshotted deliveries · min ${report.minSamples} per bracket`);
+    if (report.totalDeliveries === 0) {
+        lines.push('  (no delivery has a forecast snapshot yet — nothing to join)');
+        return lines.join('\n') + '\n';
+    }
+    for (const b of report.brackets) {
+        if (b.status === 'measured') {
+            const pct = ((b.rejectionRate ?? 0) * 100).toFixed(1);
+            const lo = ((b.interval?.lower ?? 0) * 100).toFixed(1);
+            const hi = ((b.interval?.upper ?? 0) * 100).toFixed(1);
+            lines.push(`  ${b.bracket.padEnd(6)} ≥${pct}% rejected (${b.rejected}/${b.delivered}, 95% CI ${lo}–${hi}%)`);
+        }
+        else {
+            lines.push(`  ${b.bracket.padEnd(6)} insufficient (${b.rejected}/${b.delivered} deliveries < ${report.minSamples} — rate withheld)`);
+        }
+    }
+    const verdict = report.comparison.status === 'measured'
+        ? `→ ${(0, sanitize_1.sanitizeField)(report.comparison.reason)}`
+        : `→ inconclusive: ${(0, sanitize_1.sanitizeField)(report.comparison.reason)}`;
+    lines.push(`  ${verdict}`);
+    return lines.join('\n') + '\n';
+}
+/**
+ * `lumo outcome rate [--min N] [--json]` — read the workspace trust × post-hoc-
+ * fate join: per delivery-time forecast-confidence bracket, the post-hoc
+ * REJECTED rate from the outcome well. Honest by construction — thin brackets
+ * read `insufficient` (no fabricated rate) and the high-vs-low comparison stays
+ * `inconclusive` until the well has enough signal to tell the brackets apart.
+ */
+async function outcomeRate(options = {}) {
+    const auth = authBase();
+    if ('error' in auth) {
+        console.error(`Error: ${auth.error}`);
+        return 1;
+    }
+    let min;
+    if (options.min !== undefined && options.min.trim() !== '') {
+        const n = Number(options.min);
+        if (!Number.isInteger(n) || n < 1) {
+            console.error('Error: --min must be a positive integer');
+            return 1;
+        }
+        min = n;
+    }
+    const qs = min !== undefined ? `?min=${min}` : '';
+    let res;
+    try {
+        res = await fetch(`${auth.base}/api/outcome/rate${qs}`, {
+            headers: auth.headers,
+        });
+    }
+    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) {
+        console.error(`Error: could not read the outcome rate (HTTP ${res.status}).`);
+        return 1;
+    }
+    const report = (await res.json());
+    if (options.json) {
+        process.stdout.write(JSON.stringify(report, null, 2) + '\n');
+        return;
+    }
+    process.stdout.write(formatRate(report));
+    return;
+}

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

@@ -5,6 +5,7 @@ exports.taskCriteriaList = taskCriteriaList;
 const config_1 = require("../lib/config");
 const api_1 = require("../lib/api");
 const sanitize_1 = require("../lib/sanitize");
+const referent_kind_1 = require("../../../shared/src/referent-kind");
 /**
  * Render criteria rows for stdout. One line per criterion —
  * `<id>  [TYPE]  SOURCE@rN  statement` — plus an indented checkpointer line
@@ -16,7 +17,13 @@ function formatCriteriaRows(criteria) {
     for (const c of criteria) {
         const provenance = `${c.source}@r${c.addedAtRound}`;
         const evidence = c.evidenceRequired ? '  [evidence]' : '';
-        lines.push(`${c.id}  [${c.verifierType}]  ${provenance}${evidence}  ${(0, sanitize_1.sanitizeField)(c.statement)}`);
+        const eff = (0, referent_kind_1.effectiveReferentKind)({
+            declared: c.referentKind ?? null,
+            verifierType: c.verifierType,
+            checkpointer: c.checkpointer,
+        });
+        const kindTag = ` ⟨${eff}⟩`;
+        lines.push(`${c.id}  [${c.verifierType}]  ${provenance}${evidence}${kindTag}  ${(0, sanitize_1.sanitizeField)(c.statement)}`);
         if (c.checkpointer) {
             lines.push(`  ↳ check: ${(0, sanitize_1.sanitizeField)(c.checkpointer)}`);
         }

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

@@ -1,5 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.verifyReadback = verifyReadback;
 exports.taskCriteriaSet = taskCriteriaSet;
 const config_1 = require("../lib/config");
 const api_1 = require("../lib/api");
@@ -7,6 +8,31 @@ const doc_input_1 = require("../lib/doc-input");
 const path_guard_1 = require("../lib/path-guard");
 const sanitize_1 = require("../lib/sanitize");
 const task_criteria_list_1 = require("./task-criteria-list");
+/**
+ * Landing-integrity read-back (LUM-602): a 200 OK proves absence of error,
+ * not presence of correct content. Compare what the server stored (echoed in
+ * the PUT response) field-by-field against what we submitted; any divergence
+ * means the value was corrupted in transport/landing.
+ */
+function verifyReadback(submitted, stored) {
+    const issues = [];
+    const storedByStatement = new Map(stored.map(c => [c.statement, c]));
+    for (const s of submitted) {
+        const got = storedByStatement.get(s.statement);
+        if (!got) {
+            issues.push(`criterion not found after write: "${s.statement.slice(0, 60)}"`);
+            continue;
+        }
+        const wantCk = s.checkpointer ?? null;
+        if ((got.checkpointer ?? null) !== wantCk) {
+            issues.push(`checkpointer corrupted in landing for "${s.statement.slice(0, 40)}": sent ${JSON.stringify(wantCk)}, stored ${JSON.stringify(got.checkpointer ?? null)}`);
+        }
+        if (s.referentKind != null && got.referentKind !== s.referentKind) {
+            issues.push(`referentKind corrupted in landing for "${s.statement.slice(0, 40)}": sent ${s.referentKind}, stored ${got.referentKind}`);
+        }
+    }
+    return issues;
+}
 const CAUSE_TAGS = [
     'NEW_INFO',
     'SCOPE_CHANGE',
@@ -28,7 +54,7 @@ function parseCriteriaJson(raw) {
     if (!Array.isArray(parsed) || parsed.length === 0) {
         return {
             ok: false,
-            error: 'expected a non-empty JSON array of criteria, e.g. [{"statement":"…","verifierType":"MACHINE","checkpointer":"npx jest …"}]',
+            error: 'expected a non-empty JSON array of criteria, e.g. [{"statement":"…","verifierType":"MACHINE","checkpointer":"npx jest …","referentKind":"AGENT_CONSTRUCTED_STATE"}]',
         };
     }
     return { ok: true, items: parsed };
@@ -171,4 +197,12 @@ async function taskCriteriaSet(identifier, options) {
     if (data.judgeStepsWarning) {
         process.stdout.write(`⚠ ${(0, sanitize_1.sanitizeField)(data.judgeStepsWarning)}\n`);
     }
+    const readbackIssues = verifyReadback(criteriaItems, data.criteria);
+    if (readbackIssues.length > 0) {
+        for (const issue of readbackIssues) {
+            console.error(`⚠ landing-integrity: ${(0, sanitize_1.sanitizeField)(issue)}`);
+        }
+        console.error('Error: stored contract does not match what was submitted — do not trust the success receipt. Re-run and verify.');
+        return 1;
+    }
 }