@lumoai/cli 1.41.0 → 1.42.0

package/assets/skill/references/criteria.md

@@ -1,165 +1,78 @@
 # Acceptance criteria (contract)
 
-The acceptance contract is a small set of structured criteria the task's work
-will be verified against (Acceptance v1, LUM-341/342). The agent drafts it;
-the server validates and stores it; verification rounds (`lumo verify`,
-Slice 1 task #3) judge against it. Criteria are injected at session start and
-in `lumo task context` as the `## Acceptance criteria (contract)` section.
+The acceptance contract is a small set of structured criteria the task's work is verified against (Acceptance v1, LUM-341/342). The agent drafts it; the server validates and stores it; verification rounds (`lumo verify`, Slice 1 task #3) judge against it. Criteria are injected at session start and in `lumo task context` as the `## Acceptance criteria (contract)` section.
 
 ## When to draft — the golden rule
 
 **Attach → read context → draft criteria → THEN write the first line of code.**
 
-If `lumo task context` / session-start shows the draft reminder ("This task
-has no acceptance criteria yet. …") instead of a
-contract, you MUST draft and submit criteria before starting implementation:
-
-1. Read the task description, comments, linked resources, and memory first —
-   the contract distills what "done" means, so understand the task before
-   writing it.
-2. Draft **3–7 criteria** for a typical multi-file task (soft range — the
-   server warns outside it but never rejects; if you genuinely need more,
-   merge related checks instead). **Scale the count down for small tasks** —
-   see "Scale the contract to the task size" below.
-3. Submit with `lumo task criteria set <task> --file <criteria.json>`.
-
-**The contract is editable until DONE — but changes after work starts leave a
-recorded drift trail.** The 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):
-
-- **Work has never started** (`workStartedAt` unset, task still in its initial
-  TODO phase): a `criteria set` resubmit replaces the whole contract freely —
-  full-group replace, recorded as `AGENT_DRAFT@round0`. Iterate as much as
-  needed during planning.
-- **Work has started** (the task left TODO at least once): a `criteria set`
-  resubmit is **still allowed** and applies an **identity-preserving diff** — the
-  CLI matches submitted items to existing criteria by id (attaching ids
-  automatically by exact-statement match) and records each add, update, or delete
-  as a `CRITERION_CHANGED` drift event at the current round. **No 409.** The
-  intent: the contract can be sharpened as understanding grows, but every change
-  is traceable.
-- **Task is DONE**: the contract locks — a `criteria set` resubmit is rejected
-  with 409. Reopen the task (move it back to in_progress) to change criteria, or
-  use `--human`.
-
-`--human` revisions are allowed in every non-DONE stage. One deletion rule holds
-across all stages: a criterion that already has verification runs is
-**soft-deleted** (kept for audit, runs preserved) rather than hard-deleted; a
-run-free criterion is hard-deleted. Either way, reword rather than delete when
-possible.
+If `lumo task context` / session-start shows the draft reminder ("This task has no acceptance criteria yet. …") instead of a contract, you MUST draft and submit criteria before starting implementation:
+
+1. Read the task description, comments, linked resources, and memory first — the contract distills what "done" means, so understand the task before writing it.
+2. Draft **3–7 criteria** 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 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                                                                                                                                                                                                                                                                                                       |
+| ------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Work never started** (`workStartedAt` unset, still initial TODO) | Replaces the whole contract freely — full-group replace, recorded `AGENT_DRAFT@round0`. Iterate as much as needed during planning.                                                                                                                                                                                                      |
+| **Work started** (task left TODO at least once)                    | Still allowed; applies an **identity-preserving diff** — CLI matches items to existing criteria by id (auto-attaching ids by exact-statement match), records each add/update/delete as a `CRITERION_CHANGED` drift event at the current round. **No 409.** Contract can be sharpened as understanding grows; every change is traceable. |
+| **Task DONE**                                                      | Contract locks — resubmit rejected with **409**. Reopen the task (move back to in_progress) to change criteria, or use `--human`.                                                                                                                                                                                                       |
+
+`--human` revisions are allowed in every non-DONE stage. One deletion rule holds across all stages:
+
+- A criterion that **already has verification runs** is **soft-deleted** (kept for audit, runs preserved).
+- A **run-free** criterion is **hard-deleted**.
+- Either way, reword rather than delete when possible.
 
 ### A send-back may mean the contract was wrong — amend it, don't spin off
 
-If a send-back reveals the **contract itself** was wrong or incomplete, the right
-move is to **amend the criteria on this task** (`lumo task criteria set <id>`,
-and with `--human` annotate the reason via `--cause NEW_INFO | SCOPE_CHANGE |
-DRAFT_BLIND_SPOT`) and re-verify — **not** to open a new task. Sharpening the
-contract as understanding grows is expected; that's what the drift trail is
-_for_, not something to avoid. **The line:** amending to reflect reality is
-legitimate; **weakening a criterion you were just FAILed on, purely to make it
-pass, is tampering** — it's audited and counts as a failure either way. Deleting
-a failed criterion doesn't help: the DONE gate still blocks on its standing FAIL
-(the run is soft-deleted, the verdict survives).
+If a send-back reveals the **contract itself** was wrong or incomplete, **amend the criteria on this task** (`lumo task criteria set <id>`, and with `--human` annotate the reason via `--cause NEW_INFO | SCOPE_CHANGE | DRAFT_BLIND_SPOT`) and re-verify — **not** open a new task. Sharpening the contract as understanding grows is expected; that's what the drift trail is _for_.
+
+**The line:** amending to reflect reality is legitimate; **weakening a criterion you were just FAILed on, purely to make it pass, is tampering** — audited, and counts as a failure either way. Deleting a failed criterion doesn't help: the DONE gate still blocks on its standing FAIL (the run is soft-deleted, the verdict survives).
 
 ## Scale the contract to the task size
 
-The 3–7 range is calibrated for typical multi-file tasks. The criterion count
-must track the size of the work — it is not a fixed ritual:
-
-- **Micro task** (expected to fit a single session, blast radius of one or
-  two files — a docs tweak, a copy change, a small targeted fix): **1–2
-  criteria IS a complete contract** — one targeted MACHINE criterion plus at
-  most one HUMAN criterion.
-- **Never pad toward the soft floor.** A filler criterion (a restated
-  baseline, a third angle on the same check) dilutes the contract and taxes
-  every verification round. For a micro task the below-minimum warning is
-  expected — ignore it.
-- **Shrink the contract, never skip it.** Every task still drafts and locks a
-  contract before the first line of code; task size only changes how many
-  criteria that takes.
+The 3–7 range is calibrated for typical multi-file tasks. Criterion count must track the size of the work — it is not a fixed ritual:
+
+- **Micro task** (fits a single session, blast radius of one or two files — a docs tweak, copy change, small targeted fix): **1–2 criteria IS a complete contract** — one targeted MACHINE criterion plus at most one HUMAN criterion.
+- **Never pad toward the soft floor.** A filler criterion (a restated baseline, a third angle on the same check) dilutes the contract and taxes every verification round. For a micro task the below-minimum warning is expected — ignore it.
+- **Shrink the contract, never skip it.** Every task drafts and locks a contract before the first line of code; task size only changes how many criteria that takes.
 
 ## How to write good criteria
 
-- **Outcome-level definition of done, not micro-steps.** A criterion states a
-  verifiable result ("`lumo task criteria set` rejects a second agent draft
-  with 409"), not a task step ("add a check in the service").
-- **Repo-wide baselines don't take slots.** Tests pass / `tsc --noEmit` clean /
-  i18n locale parity / lint are already required by the repo's PR checklist —
-  never spend one of your 3–7 criteria on them.
-- **MACHINE vs HUMAN:**
-  - `MACHINE` = an executable check exists. It **must** carry a `checkpointer`
-    (the runnable check: a test command, script, probe…). The checkpointer
-    runs on the agent's machine; the structured verdict is reported back to
-    the server (execution on the client, adjudication on the server).
-  - `HUMAN` = needs human judgment (UX feel, copy tone, design fidelity).
-  - **If you can't attach a checkpointer to a MACHINE criterion, demote it to
-    HUMAN** — the server rejects checkpointer-less MACHINE criteria rather
-    than silently rewriting them. Don't invent a fake checkpointer to keep it
-    MACHINE.
-  - **Jest-by-name checkpointers must go through the zero-match guard.** A
-    bare `npx jest -t '<name>'` exits 0 even when the pattern matches **no**
-    test — rename or delete the test and the checkpointer silently fake-PASSes
-    (same trap class as the BSD-grep `-P` incident, LUM-401). Write
-    `npx tsx scripts/jest-t.ts '<exact test name>' [test file path]` instead:
-    it fails unless ≥1 matching test ran and passed. The optional path scopes
-    the run to one file (much faster than name-filtering the whole suite).
-  - **A checkpointer must be instance-independent — never self-comparing.** It
-    is stored once and re-run for the life of the task, so it must not depend on
-    a baseline that shifts under it. The trap is a `vs origin/main`
-    self-comparison ("current file is strictly smaller than origin/main"): it
-    passes pre-merge, but the moment the change merges, every branch cut from
-    main has `current == base` and the check fails forever (LUM-433 c1, fixed in
-    #528). Anchor to a **fixed, absolute target** instead — a literal budget
-    (`byteCount ≤ 9500`), a committed fixture, or a stable named test run through
-    the zero-match guard. A jest-by-name checkpointer likewise rots when its test
-    is renamed or deleted — often by _another_ task's work, so the stored PASS
-    goes stale invisibly. Keep test names stable; `scripts/checkpointer-drift.ts`
-    statically sweeps stored contracts for these zero-match checkpointers
-    (`npx tsx scripts/checkpointer-drift.ts <LUM-N> | --mine`, detection-only).
-- `evidenceRequired: true` marks criteria whose verdict must point at proof
-  (a MACHINE PASS always requires evidence regardless of this flag).
-- **Edited a MACHINE checkpointer mid-task? Re-run `lumo verify`.** A prior PASS
-  was recorded against the old command — once you swap the checkpointer (or
-  reword the criterion) that pass goes stale: `lumo task status` / the acceptance
-  tab flag it `⚠ pre-edit version` (LUM-457). The stale pass still counts as met
-  (render-only, doesn't block DONE), but re-verify so the green reflects the
-  current check.
+- **Outcome-level definition of done, not micro-steps** — a verifiable result (`"lumo task criteria set rejects a second agent draft with 409"`), not a task step ("add a check in the service").
+- **Repo-wide baselines don't take slots** — tests pass / `tsc --noEmit` clean / i18n locale parity / lint are already required by the repo's PR checklist; never spend one of your 3–7 criteria on them.
+- `evidenceRequired: true` — marks criteria whose verdict must point at proof (a MACHINE PASS always requires evidence regardless of this flag).
+- **Edited a MACHINE checkpointer mid-task? Re-run `lumo verify`.** A prior PASS was recorded against the old command — swapping the checkpointer (or rewording the criterion) makes that pass stale: `lumo task status` / the acceptance tab flag it `⚠ pre-edit version` (LUM-457). The stale pass still counts as met (render-only, doesn't block DONE), but re-verify so the green reflects the current check.
+
+**MACHINE vs HUMAN:**
+
+- `MACHINE` — an executable check exists. **Must** carry a `checkpointer` (the runnable check: a test command, script, probe…). The checkpointer runs on the agent's machine; the structured verdict is reported back to the server (execution on the client, adjudication on the server).
+- `HUMAN` — needs human judgment (UX feel, copy tone, design fidelity).
+- `checkpointer`-less MACHINE → demote to HUMAN — the server rejects checkpointer-less MACHINE criteria rather than silently rewriting them. Don't invent a fake checkpointer to keep it MACHINE.
+
+**Two checkpointer traps:**
+
+- `npx tsx scripts/jest-t.ts '<exact test name>' [test file path]` — jest-by-name checkpointers must go through this zero-match guard. A bare `npx jest -t '<name>'` exits 0 even when the pattern matches **no** test — rename or delete the test and the checkpointer silently fake-PASSes (same trap class as the BSD-grep `-P` incident, LUM-401). `jest-t.ts` fails unless ≥1 matching test ran and passed; the optional path scopes the run to one file (much faster than name-filtering the whole suite).
+- `instance-independent, never self-comparing` — a checkpointer is stored once and re-run for the life of the task, so it must not depend on a baseline that shifts under it. The trap is a `vs origin/main` self-comparison ("current file is strictly smaller than origin/main"): passes pre-merge, but the moment the change merges every branch cut from main has `current == base` and the check fails forever (LUM-433 c1, fixed in #528). Anchor to a **fixed, absolute target** — a literal budget (`byteCount ≤ 9500`), a committed fixture, or a stable named test through the zero-match guard. A jest-by-name checkpointer likewise rots when its test is renamed/deleted — often by _another_ task's work, so the stored PASS goes stale invisibly. Keep test names stable; `npx tsx scripts/checkpointer-drift.ts <LUM-N> | --mine` statically sweeps stored contracts for these zero-match checkpointers (detection-only).
 
 ### judgeSteps — agent-drafted judging steps for HUMAN criteria (LUM-465)
 
-A HUMAN criterion is judged by a person, not a checkpointer — so don't hand them
-a bare assertion ("the copy reads naturally") and make them reverse-engineer
-what to do. Attach **`judgeSteps`**: short, human-readable instructions the
-adjudication card renders verbatim (light markdown, URLs are made clickable).
-Structured labour is yours; the human just follows the steps.
+A HUMAN criterion is judged by a person, not a checkpointer — so don't hand them a bare assertion ("the copy reads naturally") and make them reverse-engineer what to do. Attach **`judgeSteps`**: short, human-readable instructions the adjudication card renders verbatim (light markdown, URLs made clickable). Structured labour is yours; the human just follows the steps.
 
 **Shape — 1–3 steps, always in this order:**
 
-1. **Where to look** — the exact link or path (a task URL, a tab, a file). Paste
-   the real URL; the card/`lumo task status` render it clickable.
-2. **What to do** — the concrete action ("open the acceptance tab", "read the
-   `judgeSteps` block aloud", "resize to mobile width").
-3. **✓ pass / ✗ send-back** — the decision rule, both directions, so the verdict
-   isn't a coin-flip ("pass if every URL opens; send back if any step is vague").
-
-**One criterion = one judgment point.** If a HUMAN criterion bundles two checks,
-split it — each half gets its own steps. The canonical miss is LUM-397's "additive
-schema **and** self-credit not implemented": those are two assertions; the first
-is even machine-able (below), the second is a separate human read.
-
-**Machine-able → make it MACHINE, don't burn human attention.** Before writing
-`judgeSteps`, ask whether a checkpointer could decide it. "The migration is purely
-additive" → `grep` the `migration.sql` for `DROP`/destructive DDL → MACHINE. "No
-file under `prisma/migrations/` was deleted" → a `git diff` probe → MACHINE.
-Reserve HUMAN + `judgeSteps` for genuine taste/feel/fidelity judgments a check
-can't make.
-
-`judgeSteps` is **optional and non-blocking** — a HUMAN criterion without it still
-submits, but the server returns a soft warning (same channel as the 3–7 count
-warning) and the card shows a "no judging guidance" fallback. It is part of the
-contract: editing it drifts like any other field (`CRITERION_CHANGED` before/after
-carries it), and it survives a statement-only web edit.
+1. `Where to look` — the exact link or path (a task URL, a tab, a file). Paste the real URL; the card / `lumo task status` render it clickable.
+2. `What to do` — the concrete action ("open the acceptance tab", "read the `judgeSteps` block aloud", "resize to mobile width").
+3. `✓ pass / ✗ send-back` — the decision rule, both directions, so the verdict isn't a coin-flip ("pass if every URL opens; send back if any step is vague").
+
+**One criterion = one judgment point.** If a HUMAN criterion bundles two checks, split it — each half gets its own steps. The canonical miss is LUM-397's "additive schema **and** self-credit not implemented": two assertions; the first is even machine-able (below), the second is a separate human read.
+
+**Machine-able → make it MACHINE, don't burn human attention.** Before writing `judgeSteps`, ask whether a checkpointer could decide it. "The migration is purely additive" → `grep` the `migration.sql` for `DROP`/destructive DDL → MACHINE. "No file under `prisma/migrations/` was deleted" → a `git diff` probe → MACHINE. Reserve HUMAN + `judgeSteps` for genuine taste/feel/fidelity judgments a check can't make.
+
+`judgeSteps` is **optional and non-blocking** — a HUMAN criterion without it still submits, but the server returns a soft warning (same channel as the 3–7 count warning) and the card shows a "no judging guidance" fallback. It is part of the contract: editing it drifts like any other field (`CRITERION_CHANGED` before/after carries it), and it survives a statement-only web edit.
 
 ```json
 {
@@ -171,71 +84,32 @@ carries it), and it survives a statement-only web edit.
 
 ### Invariant (negative-assertion) criteria
 
-Most criteria assert that **something that should happen, happened** ("the
-endpoint returns 409", "the section renders"). An _invariant criterion_ asserts
-the dual: that **something that must not happen, didn't** — the change left an
-explicit don't-touch surface intact. This is the acceptance analogue of
-AppWorld's _collateral-damage_ checks (arXiv 2407.18901) and ToolSandbox's
-_minefield_ states (arXiv 2408.04682): a finished task should be judged not only
-on the intended effect but on the forbidden effects it avoided. `lumo verify`
-already judges final state per round, so an invariant fits the existing
-machinery with no new mechanism — it's a drafting habit, not a feature.
-
-**When to write one.** Add a single invariant criterion when the task has a
-concrete, nameable surface the change must not disturb — a data-destruction red
-line, a structure guard, an always-green baseline set, a diff that must stay
-in-bounds, a standing budget. It is decision support, not a ritual: reach for it
-only when you can point at the surface. If the only invariant you can name is
-"don't break the build", that's already the repo's PR baseline (tests / `tsc` /
-lint / i18n parity) — don't spend a slot restating it.
-
-**How to phrase it.** State the invariant as _still holding after the change_,
-not as a step you took. The **c-CRAB boundary** is the hard rule: the check
-encodes **"the problem does not (re)occur"**, never **"a specific fix exists"**.
-Write "`prisma/migrations/` has no deleted files vs origin/main" (the bad state
-is absent) — not "the migration-delete guard function is present" (a named fix).
-The first survives a refactor of _how_ the invariant is enforced; the second
-re-fails the moment someone renames the guard, and passes even if the protection
-was gutted some other way.
-
-**Pairing with a checkpointer.** An invariant almost always has a runnable check
-— that's its advantage — so prefer MACHINE. The existing `checkpointer` syntax
-carries it as-is: a `git diff` path/filter probe, a full-suite `jest` run, a
-structure-verify script, a parity check. Two real-repo examples:
-
-- **`prisma/migrations/` files are never deleted** (the CLAUDE.md red line). The
-  bad state is a deleted migration file in the diff:
-
-  ```json
+Most criteria assert that **something that should happen, happened** ("the endpoint returns 409", "the section renders"). An _invariant criterion_ asserts the dual: that **something that must not happen, didn't** — the change left an explicit don't-touch surface intact. This is the acceptance analogue of AppWorld's _collateral-damage_ checks (arXiv 2407.18901) and ToolSandbox's _minefield_ states (arXiv 2408.04682): a finished task is judged not only on the intended effect but on the forbidden effects it avoided. `lumo verify` already judges final state per round, so an invariant fits the existing machinery with no new mechanism — a drafting habit, not a feature.
+
+- `When to write one` — add a single invariant criterion when the task has a concrete, nameable surface the change must not disturb: a data-destruction red line, a structure guard, an always-green baseline set, a diff that must stay in-bounds, a standing budget. Decision support, not a ritual: reach for it only when you can point at the surface. If the only invariant you can name is "don't break the build", that's already the repo's PR baseline (tests / `tsc` / lint / i18n parity) — don't spend a slot restating it.
+- `How to phrase it` — state the invariant as _still holding after the change_, not as a step you took. The **c-CRAB boundary** is the hard rule: encode **"the problem does not (re)occur"**, never **"a specific fix exists"**. Write "`prisma/migrations/` has no deleted files vs origin/main" (the bad state is absent) — not "the migration-delete guard function is present" (a named fix). The first survives a refactor of _how_ the invariant is enforced; the second re-fails the moment someone renames the guard, and passes even if the protection was gutted some other way.
+- `Pairing with a checkpointer` — an invariant almost always has a runnable check (its advantage), so prefer MACHINE. The existing `checkpointer` syntax carries it as-is: a `git diff` path/filter probe, a full-suite `jest` run, a structure-verify script, a parity check.
+
+Two real-repo invariant examples — `prisma/migrations/` files never deleted (the CLAUDE.md red line), and a live-doc's table structure not flattened (the LUM-349 incident: an HTML→md round-trip silently collapsed tables to plain text):
+
+```json
+[
   {
     "statement": "No file under prisma/migrations/ is deleted by this change (vs origin/main)",
     "verifierType": "MACHINE",
     "checkpointer": "bash -c \"test -z \\\"$(git diff --diff-filter=D --name-only origin/main -- prisma/migrations/)\\\"\""
-  }
-  ```
-
-- **A live-doc's table structure is not flattened** (the LUM-349 incident: an
-  HTML→md round-trip silently collapsed tables to plain text). The verify script
-  hard-fails if any table / row / heading count shrank:
-
-  ```json
+  },
   {
     "statement": "Live-doc keeps its table structure after the edit (no rows/headings dropped)",
     "verifierType": "MACHINE",
     "checkpointer": "npx tsx scripts/verify-live-doc.ts <docId> docs/live-docs/<file>.md"
   }
-  ```
+]
+```
 
-A third lives in a current contract you can copy: **LUM-415**'s "SKILL.md
-frontmatter description stays ≤ 1000 chars" — the standing context-budget
-invariant (the description is resident in every session), checkpointed by the
-`description cap` case in
-`scripts/analysis/lum392-cli-friction/__tests__/doc-examples.test.ts`.
+A third lives in a current contract you can copy: **LUM-415**'s "SKILL.md frontmatter description stays ≤ 1000 chars" — the standing context-budget invariant (the description is resident in every session), checkpointed by the `description cap` case in `scripts/analysis/lum392-cli-friction/__tests__/doc-examples.test.ts`.
 
-One invariant criterion is usually enough — it's the guardrail, not the whole
-contract. Pair it with the positive criteria that say what the change should
-achieve; together they assert _did the right thing_ **and** _touched nothing
-it shouldn't_.
+One invariant criterion is usually enough — it's the guardrail, not the whole contract. Pair it with the positive criteria that say what the change should achieve; together they assert _did the right thing_ **and** _touched nothing it shouldn't_.
 
 ## JSON file format
 
@@ -262,73 +136,53 @@ it shouldn't_.
 ]
 ```
 
-Fields: `statement` (required, ≤2000 chars), `verifierType` (`"MACHINE"` |
-`"HUMAN"`), `checkpointer` (required for MACHINE), `evidenceRequired`
-(optional, default false), `judgeSteps` (optional, ≤2000 chars — agent-drafted
-human-judging steps for a HUMAN criterion; see "judgeSteps" above), `id` (only
-in `--human` revisions — see below).
+Fields:
+
+- `statement` — required, ≤2000 chars.
+- `verifierType` — `"MACHINE"` | `"HUMAN"`.
+- `checkpointer` — required for MACHINE.
+- `evidenceRequired` — optional, default false.
+- `judgeSteps` — optional, ≤2000 chars; agent-drafted human-judging steps for a HUMAN criterion (see "judgeSteps" above).
+- `id` — only in `--human` revisions (see below).
 
 ## Commands
 
 ### `lumo task criteria set <task> --file <criteria.json>`
 
-Agent draft, recorded as `AGENT_DRAFT` at round 0. **Editable until DONE:**
-while `workStartedAt` is unset (task never left TODO) a resubmit replaces the
-whole contract (full-group baseline). Once work has started an agent resubmit
-applies an **identity-preserving diff** — matched by id, with each add/update/
-delete recorded as a `CRITERION_CHANGED` drift event; no 409. The contract locks
-(409) only once the task is **DONE** — reopen it to change criteria, or use
-`--human`. A criterion that already has verification runs is soft-deleted (audit
-trail preserved) rather than hard-deleted; run-free criteria are hard-deleted.
-Echoes the stored criteria (with ids) plus the 3–7 soft-cap warning if outside
-range.
+Agent draft, recorded as `AGENT_DRAFT` at round 0. **Editable until DONE:** while `workStartedAt` is unset (task never left TODO) a resubmit replaces the whole contract (full-group baseline). Once work has started an agent resubmit applies an **identity-preserving diff** — matched by id, each add/update/delete recorded as a `CRITERION_CHANGED` drift event; no 409. The contract locks (409) only once the task is **DONE** — reopen it to change criteria, or use `--human`. A criterion that already has verification runs is soft-deleted (audit trail preserved); run-free criteria are hard-deleted. Echoes the stored criteria (with ids) plus the 3–7 soft-cap warning if outside range. `--file` must point inside the current project directory — write the JSON to the repo root or a subdirectory, not `/tmp`, and delete it after submission.
 
 ```bash
 lumo task criteria set LUM-42 --file criteria-lum42.json
 ```
 
-(`--file` must point inside the current project directory — write the JSON to
-the repo root or a subdirectory, not `/tmp`, and delete it after submission.)
-
 ### `lumo task criteria set <task> --file <criteria.json> --human`
 
-Record a **human contract revision** (HUMAN_EDIT), e.g. when the user changes
-the contract in conversation — you transcribe their decision. Allowed at any
-time, even after the agent lock. The file is the **desired final list**:
+Record a **human contract revision** (HUMAN_EDIT), e.g. when the user changes the contract in conversation — you transcribe their decision. Allowed at any time, even after the agent lock. The file is the **desired final list**:
 
-- items carrying an `id` (from `criteria list`) keep that criterion — changed
-  fields update it and stamp it `HUMAN_EDIT`; identical fields leave it (and
-  its provenance) untouched
-- items without `id` are created as `HUMAN_EDIT`
-- existing criteria missing from the file are **deleted** — refused with 409
-  if the criterion already has verification runs (reword it instead)
+- `id` present (from `criteria list`) — keeps that criterion; changed fields update it and stamp it `HUMAN_EDIT`; identical fields leave it (and its provenance) untouched
+- `id` absent — the item is created as `HUMAN_EDIT`
+- `id` missing-from-file — existing criteria not in the file are **deleted**; refused with 409 if the criterion already has verification runs (reword it instead)
 
-The revision is auto-recorded as a task comment with the session origin
-(`X-Lumo-Session-Id`). **Transcribing the contract is allowed; transcribing a
-verdict is never** — human verdicts only enter through human-initiated paths
-(web UI / Slack action), and the agent has no write path to them.
-
-Only use `--human` for decisions a human actually made (in conversation, in a
-comment, in review). Never use it to work around your own lock.
+The revision is auto-recorded as a task comment with the session origin (`X-Lumo-Session-Id`). **Transcribing the contract is allowed; transcribing a verdict is never** — human verdicts only enter through human-initiated paths (web UI / Slack action), and the agent has no write path to them. Only use `--human` for decisions a human actually made (in conversation, in a comment, in review). Never use it to work around your own lock.
 
 ```bash
 lumo task criteria set LUM-42 --file criteria-revision.json --human
 lumo task criteria set LUM-42 --file criteria-revision.json --human --cause SCOPE_CHANGE
 ```
 
-Optionally annotate **why** the contract drifted with
-`--cause <NEW_INFO|SCOPE_CHANGE|DRAFT_BLIND_SPOT|GRANULARITY|OTHER>` — pick
-the tag from the human's stated reason (new information, scope moved, the
-draft missed it, wrong granularity). The tag lands in the drift record
-(TaskActivity payload), feeding the Slice-3 drift-cause distribution. Every
-criteria add/update/delete is mirrored as a structured `CRITERION_CHANGED`
-activity automatically; `--cause` just enriches it.
+Optionally annotate **why** the contract drifted with `--cause <NEW_INFO|SCOPE_CHANGE|DRAFT_BLIND_SPOT|GRANULARITY|OTHER>` — pick the tag from the human's stated reason:
+
+- `NEW_INFO` — new information.
+- `SCOPE_CHANGE` — scope moved.
+- `DRAFT_BLIND_SPOT` — the draft missed it.
+- `GRANULARITY` — wrong granularity.
+- `OTHER` — anything else.
+
+The tag lands in the drift record (TaskActivity payload), feeding the Slice-3 drift-cause distribution. Every criteria add/update/delete is mirrored as a structured `CRITERION_CHANGED` activity automatically; `--cause` just enriches it.
 
 ### `lumo task criteria list <task>`
 
-Print the contract: `<id>  [MACHINE|HUMAN]  SOURCE@rN  [evidence]  statement`
-plus an indented `↳ check:` line for checkpointers. Use it to fetch ids
-before a `--human` revision. Empty contract prints a drafting pointer.
+Print the contract: `<id>  [MACHINE|HUMAN]  SOURCE@rN  [evidence]  statement` plus an indented `↳ check:` line for checkpointers. Use it to fetch ids before a `--human` revision. Empty contract prints a drafting pointer.
 
 ```bash
 lumo task criteria list LUM-42
@@ -336,20 +190,11 @@ lumo task criteria list LUM-42
 
 ## Injection behavior
 
-- **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.
-- **`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").
+- **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.
+- **`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 (round cap 3, IN_REVIEW on
-all-pass, escalation on a round-3 fail).
+The contract is judged by `lumo verify` — run it before claiming the task is done. See [verify.md](verify.md) for the loop (round cap 3, IN_REVIEW on all-pass, escalation on a round-3 fail).

package/assets/skill/references/doc-editing.md

@@ -0,0 +1,146 @@
+# Editing live documents
+
+Commands for **reading a faithful edit base and writing back surgically** — the safe way to edit live docs (registers, ledgers, reports) without flattening tables or clobbering concurrent edits. For document CRUD, sharing, and import, see [docs.md](docs.md) (it also documents the shared **content channels** — `--content` / `--file` / stdin — and the **compact-tables authoring convention**, which apply equally to `doc patch` / `doc append`).
+
+**The red line (LUM-349):** never treat rendered `doc show` output as a re-uploadable source — HTML→markdown is lossy and flattens tables. The only legal edit base is `doc show --raw` / `--section`, which print the byte-identical stored `sourceMarkdown`.
+
+## `lumo doc show <doc> [--raw | --section <heading>]` — print one document's detail
+
+Default mode prints a key:value header (id, title, scope, project, created/updated, **revision**, mentioned tasks) and the content rendered back to markdown. `Revision:` is the body's optimistic-concurrency counter — feed it back as `--if-revision` on `doc update` / `doc patch` / `doc append`.
+
+```bash
+lumo doc show "RFC: doc CLI"
+lumo doc show cmd_xxx --raw > base.md            # byte-identical edit base (revision on stderr)
+lumo doc show cmd_xxx --section "D 状态表" > sec.md  # one section only (revision on stderr)
+```
+
+**`--raw` (LUM-408)** prints the byte-identical markdown source of the last markdown upload — no header, no trailing newline added. The server stores the raw markdown (`sourceMarkdown`) alongside the rendered HTML on every markdown write (`doc create/update --content/--file/stdin`, gdoc import/sync), so `--raw` output IS a legal edit base: `doc show --raw > base.md`, edit, `doc update --file base.md` round-trips losslessly.
+
+- A web-editor (HTML-direct) edit or revision restore **invalidates** the stored source — the doc's markdown source is gone until the next markdown upload.
+- When no source is stored (legacy doc or after an HTML edit), `--raw` **fails with exit 1 and a rebuild hint** — it never silently falls back to the lossy HTML→markdown reverse render (that fallback flattened tables: LUM-349). Rebuild flow (LUM-446): run **`lumo doc rebuild-source <doc>`** — it regenerates the source from the stored HTML with a lossless serializer (tables round-trip) and a structure guard, so `--raw` works from then on.
+- Raw output is verbatim (unsanitized) by design — redirect it to a file rather than reading it in a terminal when the doc's provenance is uncertain.
+
+Note: the markdown rendered by **default-mode** `doc show` is still best-effort (tables flatten). Round-trip via `doc show > tmp.md && doc update --file tmp.md` is NOT a no-op — use `--raw` as the edit base instead.
+
+Output budget (LUM-428): **default-mode** `doc show` caps the rendered body to the output-token budget (25,000 tokens) and, when truncated, ends in a pointer to `--section "<heading>"` / `--raw`. `--raw` and `--section` are **never** capped — they are byte-faithful edit bases.
+
+**`--section <heading>` (LUM-409)** prints just one heading-addressed section of the markdown source — a byte-faithful slice from the heading line through (not including) the next same-or-higher-level heading, subsections included. No header on stdout (the slice is a legal `doc patch` base); the current revision is printed to **stderr** as `Revision: N`. Mutually exclusive with `--raw`.
+
+- Section addressing: pass the heading text (`--section "D 状态表"`), matched in three tiers — exact, then case-insensitive, then (LUM-447) full-width↔half-width punctuation + whitespace normalization, so a half-width query (`问题(P4)`) lands on a full-width stored heading (`问题（P4）`) and vice-versa. Prefix with `#…` to pin the level when the same text exists at several depths (`--section "## Status"`). Normalization never relaxes the ambiguity guard — multiple matches still give the candidate list + exit 1.
+- Missing heading → exit 1 listing the available headings; ambiguous heading → exit 1 with a depth-disambiguation hint.
+- Requires a stored markdown source — same no-fallback rule and rebuild flow as `--raw`.
+- Heading detection is markdown-aware: `#` lines inside fenced code blocks or blockquotes are never section boundaries.
+
+Use default mode to read a doc; `--raw` whenever the full output will be edited and uploaded back; `--section` when only one part matters (keeps the context window small and the patch radius smaller).
+
+### When to suggest `doc show --raw` / `--section`
+
+- Before any `doc update --file` that starts from existing remote content — fetch the base with `--raw`, never from rendered `doc show` output.
+- Before a `doc patch` — read the section with `--section` first, note the `Revision:` line, edit, patch back with `--if-revision`.
+- User asks "what's the exact source of this doc", or an agent needs a faithful local copy of a live doc.
+- User asks "what's in section X" of a long doc — `--section` avoids pulling the whole body into context.
+- If `--raw`/`--section` errors (no stored source), run `lumo doc rebuild-source <doc>` to regenerate it losslessly, then retry — don't edit the rendered output.
+
+## `lumo doc patch <doc> --section <heading>` — replace one section
+
+Replaces the **whole addressed section** (heading line included, subsections included) with the provided content, server-side, leaving every byte outside the section untouched. The new content comes from `--content`, `--file`, or piped stdin (one required; `--file` is sandboxed like `doc update`).
+
+| Flag                  | Type    | Notes                                                                                                       |
+| --------------------- | ------- | ----------------------------------------------------------------------------------------------------------- |
+| `--section <heading>` | string  | Required. Heading text addressing the section; prefix `#…` pins the depth.                                  |
+| `--content <text>`    | string  | New section content (include the heading line — the whole section is replaced verbatim).                    |
+| `--file <path>`       | string  | New section content from file (project-local sandbox).                                                      |
+| `--if-revision <n>`   | int     | Only apply if the body is still at revision `n`. Recommended whenever the edit base was read earlier.       |
+| `--allow-shrink`      | boolean | Let the patch through even when it drops tables/rows/headings within the addressed section (422 otherwise). |
+
+Concurrency: the splice always commits **conditionally** on the revision the server read the source at — even without `--if-revision`, a concurrent body edit between read and write returns 409 instead of clobbering. On 409 the CLI prints the server reason plus a re-read-and-retry hint and exits 1.
+
+Structure guard (LUM-410), **scoped to the addressed section**: a replacement whose render has fewer `table`/`tr`/heading elements than the old section's render is rejected with 422 naming each shrunk category (old→new counts); structure elsewhere in the document never factors in. Dropping the heading line itself trips the guard too. Pass `--allow-shrink` when the deletion is intentional. `doc append` is pure insertion and is never guarded.
+
+Requires a stored markdown source (same rule as `--raw`); errors with the rebuild hint otherwise.
+
+```bash
+lumo doc show cmd_xxx --section "D 状态表" > sec.md   # stderr: Revision: 6
+# … edit sec.md …
+lumo doc patch cmd_xxx --section "D 状态表" --file sec.md --if-revision 6
+# → Patched cmd_xxx "登记册" § "D 状态表"  revision 7
+```
+
+### When to suggest `doc patch`
+
+- User wants to change one section of a live doc ("update the status table", "rewrite section D") — patch beats full `doc update` on clobber radius and context size.
+- Live-doc status updates that used to be read-whole/edit/upload-whole round-trips.
+- If the patch 409s: re-read the section, rebase the edit, retry — never fall back to a full-body upload from the stale base.
+- If the patch 422s (structure guard): the replacement drops tables/rows/headings the section has. Re-check the edit base first; add `--allow-shrink` only when the deletion is what the user wants.
+
+## `lumo doc append <doc> [--section <heading>]` — append to a section (or the doc)
+
+Inserts the new content at the **end of the addressed section** (just before the next same-or-higher-level heading), or at the end of the document when `--section` is omitted. Pure insertion: no pre-existing byte is modified, which makes it the natural write for running logs, ledgers and queues. Content channels and sandbox are the same as `doc patch`; separator blank lines are added automatically.
+
+| Flag                  | Type   | Notes                                                                        |
+| --------------------- | ------ | ---------------------------------------------------------------------------- |
+| `--section <heading>` | string | Optional. Omit to append at the document end.                                |
+| `--content <text>`    | string | Content to append.                                                           |
+| `--file <path>`       | string | Content from file (project-local sandbox).                                   |
+| `--if-revision <n>`   | int    | Only apply if the body is still at revision `n`; 409 + retry hint otherwise. |
+
+Same concurrency contract as `doc patch` (always a conditional commit; 409 on conflict). **End-of-document append (no `--section`) does NOT require a stored markdown source** (LUM-444): when the source is missing (web HTML edit / revision restore / legacy doc) it renders the new block to HTML and concatenates it onto the stored HTML body — so one web operation can no longer lock the whole doc against the agent write path. The source stays null (the doc is still HTML-only afterward; `--raw`/`--section`/`doc patch` keep erroring with the rebuild hint). **Section-addressed append (`--section`) still requires a stored source** — it needs the markdown to locate the heading boundary.
+
+```bash
+lumo doc append cmd_xxx --section "F 待办队列" --content "- [ ] 评估 XYZ 论文"
+# → Appended to cmd_xxx "登记册" § "F 待办队列"  revision 8
+echo "## 2026-06-10\n吸收了 3 篇" | lumo doc append cmd_xxx   # document end
+```
+
+### When to suggest `doc append`
+
+- User wants to add an entry/row/log line to a section ("把 X 加进待办队列", "append today's notes") — this is the killer op for ledger-style live docs: zero clobber risk by construction.
+- Whenever the alternative would be re-uploading the whole doc just to add lines at the end of one section.
+
+## `lumo doc diff <doc> --file <local.md>` — compare remote markdown source vs a local file
+
+Compares the server-side stored markdown source (the byte-identical last markdown upload) against a local file, making remote/local split-brain visible on demand.
+
+| Flag            | Type   | Notes                                                                             |
+| --------------- | ------ | --------------------------------------------------------------------------------- |
+| `--file <path>` | string | Required. Local markdown file; same project-local sandbox as `doc update --file`. |
+
+Exit codes: **0** = byte-identical (prints `Clean: …`), **1** = divergent (prints a unified diff, `--- remote/<id> (sourceMarkdown)` vs `+++ local/<file>`) or error. A doc without a stored markdown source errors explicitly (upload a markdown base once, then diff works).
+
+```bash
+lumo doc diff cmd_xxx --file docs/live-docs/research-intake-ledger.md
+```
+
+### When to suggest `doc diff`
+
+- Before uploading a locally edited file with `doc update --file` — check whether the remote source moved since the local copy was taken (prevents stale-upload clobbering, the #460 incident class).
+- When a repo-tracked markdown source (e.g. `docs/live-docs/`) and the live doc may have drifted and the user asks which is current.
+- After a suspected concurrent edit: a clean diff (exit 0) proves remote and local are in sync.
+
+## `lumo doc rebuild-source <doc>` — regenerate the markdown source from the HTML body
+
+The **recovery path for a source-less doc** (LUM-446). When a doc has no stored `sourceMarkdown` — a web HTML-direct edit or revision restore nulled it, or the doc predates source storage — every markdown write path (`--raw`, `--section`, `doc patch`, `doc append --section`, `doc diff`) is locked. This regenerates a valid source by serializing the **stored HTML structure model** back to markdown with a **lossless serializer that round-trips tables/rows/headings** (the default `doc show` render flattens tables — LUM-349 — so it was never a safe rebuild base). Only the `sourceMarkdown` column is backfilled; the rendered body is untouched, so the doc reads identically and you just regain the edit base.
+
+| Flag                | Type    | Notes                                                                                                                    |
+| ------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------ |
+| `--allow-shrink`    | boolean | Commit even if the rebuilt source re-renders with fewer tables/rows/headings than the stored body (default: 422 reject). |
+| `--force`           | boolean | Re-derive even when a source already exists (default: 409 — protects a byte-faithful human source from a downgrade).     |
+| `--if-revision <n>` | int     | Only apply if the body is still at this revision (from `doc show`).                                                      |
+
+The rebuild is **structure-guarded** (the same LUM-410 口径 as `doc update`/`doc patch`): if the serializer would drop any table/row/heading, it is rejected with **422** rather than silently committing a flattened source — `--allow-shrink` is the explicit escape hatch. A doc that already has a source is refused **409** unless `--force`.
+
+```bash
+lumo doc rebuild-source cmd_xxx          # restore a source-less doc; --raw works after
+lumo doc rebuild-source cmd_xxx --force  # re-derive even if a source already exists
+```
+
+### When to suggest `doc rebuild-source`
+
+- A `--raw` / `--section` / `doc patch` / `doc diff` call errored with "no stored markdown source" — rebuild, then retry. This is the first thing to try, not a manual reconstruction.
+- A table-heavy live doc (e.g. a `docs/live-docs/` registry) lost its source after a web operation and the markdown write path is locked.
+- Do **not** run it on a doc that already has a good source unless the user explicitly wants to re-derive it (then pass `--force`) — it replaces the byte-faithful source with a serializer-derived one.
+
+## Out of scope (CLI v1)
+
+- Lossless markdown round-trip from **rendered** `doc show` output (use `doc show --raw` — lossless whenever a markdown source is stored).
+- `--from-editor` (interactive $EDITOR).