docs, skill: maintain evolve --mode agent and testrun run --agent (kane-cli 0.8.21)

.agents/skills/kane-cli/SKILL.md

@@ -5,7 +5,7 @@ description: Browser automation + AI test authoring via kane-cli - run browser o
 
 # Kane CLI — Browser Automation Skill
 
-Use `kane-cli` for **any task that requires a real browser**: navigating websites, clicking elements, filling forms, searching, testing web UI, taking screenshots, or verifying deployments. Do NOT use Playwright, Puppeteer, or Selenium directly. Use `--agent` for `run` and `testmd run`. `testrun run` has no `--agent`: it emits NDJSON only when **stdin** is not a TTY, so every `testrun run` line you write ends in `< /dev/null` (bash and zsh: macOS, Linux, Git Bash; in cmd.exe write `< NUL`; from PowerShell run it through cmd: `cmd /c "kane-cli testrun run … < NUL"`). Check the first stdout line: on 0.8.17+ it is `{"type":"stream_start"…}`. A prose plan there instead means the CLI is in terminal mode: it shows the human view and, after a real run, opens an evidence table that waits until `q` or Esc, so the process never exits on its own; stop it and rerun with the redirect. An empty stdout with a message on stderr is a usage error: read it. Assurance conversational commands use `--mode agent`.
+Use `kane-cli` for **any task that requires a real browser**: navigating websites, clicking elements, filling forms, searching, testing web UI, taking screenshots, or verifying deployments. Do NOT use Playwright, Puppeteer, or Selenium directly. Use `--agent` for `run` and `testmd run`. `testrun run` emits NDJSON when **stdin** is not a TTY (0.8.21+ also takes `--agent`, which selects the same stream), so every `testrun run` line you write ends in `< /dev/null` (bash and zsh: macOS, Linux, Git Bash; in cmd.exe write `< NUL`; from PowerShell run it through cmd: `cmd /c "kane-cli testrun run … < NUL"`). Check the first stdout line: on 0.8.17+ it is `{"type":"stream_start"…}`. A prose plan there instead means the CLI is in terminal mode: it shows the human view and, after a real run, opens an evidence table that waits until `q` or Esc, so the process never exits on its own; stop it and rerun with the redirect. An empty stdout with a message on stderr is a usage error: read it. Assurance conversational commands use `--mode agent`.
 
 **Authoring test cases or scenarios?** Never write them by hand: every test case comes from the **assurance** commands — Read `references/assurance.md` first.
 
@@ -321,7 +321,7 @@ For one-shot `run`, build post-run logic on `run_end` and process exit. Saved te
 
 For full event schemas (`bifurcation` flow fields, `child_agent_*`, `ask_user` semantics, `cancel`/`user_response` outbound events, complete `run_end` field list), Read `references/parsing.md`.
 
-The assurance conversational commands (`context ingest`/`context extract`, `design tests`, `maintain reconcile`, `cover`) do NOT take `--agent` — they take **`--mode agent`** and speak their own typed stream ending in `done` (open vocabulary — tolerate unknown event types; on 0.7.2+ the stream is strict — every stdout line parses, stderr silent — while on 0.7.1 a merged `context ingest` prints a few prose receipt lines BEFORE the stream — skip to the first `{` line, harmless on 0.7.2+ — and a landing-phase ingest failure ends with prose + exit 1/2 and no stream at all: a refusal, not a crash; on 0.7.2+ those failures ride the stream as `error` + `done`); **for those commands only, exit `3` means paused-and-resumable, not timeout** — schema in `references/assurance-parsing.md`, behavior in `references/assurance.md`. The context sync verbs (`kane-cli context sync`, `kane-cli context push`, `kane-cli context pull`, `kane-cli context clone`; kane-cli 0.8.14+) take `--mode agent` the same way and speak a `sync_*` family ending in `done`; there too exit `3` means a decision or a pull is needed, not a failure — `references/context-sync.md`. `kane-cli context sync setup` refuses without a terminal (`TTY_REQUIRED`): agents use `kane-cli context sync add` and `kane-cli context clone`.
+The assurance conversational commands (`context ingest`/`context extract`, `design tests`, `maintain reconcile`, `maintain evolve` on 0.8.21+, `cover`) do NOT take `--agent` — they take **`--mode agent`** and speak their own typed stream ending in `done` (open vocabulary — tolerate unknown event types; on 0.7.2+ the stream is strict — every stdout line parses, stderr silent — while on 0.7.1 a merged `context ingest` prints a few prose receipt lines BEFORE the stream — skip to the first `{` line, harmless on 0.7.2+ — and a landing-phase ingest failure ends with prose + exit 1/2 and no stream at all: a refusal, not a crash; on 0.7.2+ those failures ride the stream as `error` + `done`); **for those commands only, exit `3` means paused-and-resumable, not timeout** — schema in `references/assurance-parsing.md`, behavior in `references/assurance.md`. The context sync verbs (`kane-cli context sync`, `kane-cli context push`, `kane-cli context pull`, `kane-cli context clone`; kane-cli 0.8.14+) take `--mode agent` the same way and speak a `sync_*` family ending in `done`; there too exit `3` means a decision or a pull is needed, not a failure — `references/context-sync.md`. `kane-cli context sync setup` refuses without a terminal (`TTY_REQUIRED`): agents use `kane-cli context sync add` and `kane-cli context clone`.
 
 `kane-cli testrun run` also emits its own typed stream (`testrun_plan` … terminal `testrun_done`) — schema in `references/testrun.md`. `kane-cli testmd run` may additionally emit `test_md_evidence_ingest` (replay evidence published) and `test_md_bundle_sync` (test bundle synced) — informational; describe in plain language, never surface raw names. The post-run evidence hint (`` evidence: view locally with `kane-cli evidence serve <path>` ``) is a **stderr** text line, not a stdout event — don't try to parse it from the NDJSON stream; see `references/evidence.md` for how to act on it.
 

.agents/skills/kane-cli/references/assurance-parsing.md

@@ -81,6 +81,26 @@ Use `text` + `options[].label` + `recommended_index` + `rationale` to decide or
 
 *(0.7.2+)* the stream opens with a minimal `run_start` (`session` only — no `trace`) and the re-extract child rides the SAME stream: extract-vocabulary events (`source_start`, `agent_activity`, `plan`, `commit`, …) interleave between the `reconcile_*` events, all stamped `verb: "reconcile"` — dispatch on `type`, never on position. The reconcile family: `reconcile_plan` `{source_id, plan_path, rows[], archive[]}` → per row `reconcile_row_start` `{kind, ref, stale?, direct?}` + `reconcile_row_end` `{kind, ref, outcome: applied|failed|skipped|plan-only|paused, exit_code?, detail?}` → `reconcile_paused` `{plan_path, pending[]}` when ARCHIVE rows remain (exit 3; a human resumes with `--apply <plan_path>` in a terminal) → `reconcile_summary` `{applied, skipped, deferred, plan_only, failed, paused, stale_created}` on every path → `done` always last. Validation refusals ride the stream as `error` + `done` (exit 2), never stderr alone.
 
+## Evolve events (verb `evolve`) *(0.8.21+)*
+
+`kane-cli maintain evolve <ref> --mode agent` (or `--from-stale`, never both) shares the envelope with `verb: "evolve"`.
+
+| Event | When | Payload |
+|---|---|---|
+| `evolve_batch` | `--from-stale`, first | `stale_nodes`, `use_cases` |
+| `evolve_target` | once per designed use-case, before any question | `ref?`, `use_case`, `pairs` (the blast radius), `because?` |
+| `evolve_paused` | a question has no answer; the run ends here, exit `3` | `pending_questions[]` (id `evolve:<use-case>`, options `proceed` / `decline`), `resume`, `next[]` (two ready commands: proceed all, decline all) |
+| `child_start` / `child_end` | around the design run, after a proceed | `child: "design"`, `subject` / `ok`, `dur_s`, `exit_code?` |
+| *(the design run's events)* | between the two, stamped `verb: "design"` | every event of `design tests --mode agent` except its `done`; a paused design session arrives as `session_paused` with `sid`, `resume`, `next[]` |
+| `evolve_diff` | after a clean design run | `use_case`, `generation` (`before`, `after`), `superseded[]`, `minted[]`, `retained[]` (pairs as `scenario` + `test`), `moves[]` (`ac`, `before[]`, `after[]`) |
+| `evolve_skipped` | a use-case not evolved | `use_case`, `reason`: `declined`, or `no-design` in a `--from-stale` batch |
+| `error` | a refusal or failure | `message`, `code?`: `MODE_USAGE` (only `interactive` and `agent` are accepted), `ANSWER_USAGE` (an answer to a question the run does not ask, or a value that is neither option) |
+| `done` | last | `status`, `exit_code`, `next?`: `complete` 0, `refused` 2, `paused` 3, `error` with the design run's own code; `next[]` carries every paused session's resume, uncapped |
+
+- **Answering.** `--answer evolve:<use-case>=1` (or `=proceed`) and `--answer evolve:<use-case>=2` (or `=decline`), repeatable, with `--mode agent`. A refused answer is `error` + `done` with nothing before it.
+- **Refusals.** An explicit target that is fresh and has no `--because`, or that was never designed, exits `2`. A `--from-stale` run with nothing stale exits `0`.
+- **Batches.** Every use-case runs whatever the earlier ones did. The exit is the first design-run code that is neither 0 nor 3; otherwise 3 if any paused; otherwise 0.
+
 ## Sync events (verb `sync`) *(0.8.14+)*
 
 `kane-cli context sync`, `kane-cli context push`, `kane-cli context pull` and `kane-cli context clone` under `--mode agent` (and `kane-cli context sync add`, `kane-cli context sync list`, `kane-cli context sync remove`, `kane-cli context sync status`, `kane-cli context sync doctor`) share the envelope with `verb: "sync"` and their own `sync_*` family — `sync_probe_started`/`sync_probe`, `sync_status`, `sync_pull_done`/`sync_push_done`, `sync_rebase_started`/`sync_rebase_decision`/`sync_rebase_done`/`sync_rebase_open`, `sync_error{code, detail, remedy}` — then `done`. Two of them cross into the assurance streams: `sync_behind` (an advisory on `extract`/`design`/`reconcile` streams: the location has records this store has not pulled — one line, not a failure) and `sync_error` code `SYNC_REBASE_PENDING` (the fence: a sync rebase is open, so the write verb refused; `verb` carries that verb's own name). Schema, refusal codes and the `--answer` loop: `references/context-sync.md`.

.agents/skills/kane-cli/references/assurance.md

@@ -28,13 +28,13 @@ On 0.7.1+, `context ingest --mode agent` lands the files and runs the extraction
 Two hard rules:
 
 1. **The two checkpoints are the user's, not yours.** Everything the extract and design agents emit is *derived* (unreviewed) until a human decision promotes it — see §4. Do not start authoring (step 5) until the user has approved the design output or explicitly told you to proceed.
-2. **One step at a time, one store-writer at a time.** Never run two store-mutating commands concurrently (`ingest`, `extract`, `review` with verdicts, `design`, `reconcile`) — the store is single-writer (§8), and extraction additionally holds a store-wide lock (a concurrent extract refuses `EXTRACT_LOCKED`, exit 2 — wait, never delete locks).
+2. **One step at a time, one store-writer at a time.** Never run two store-mutating commands concurrently (`ingest`, `extract`, `review` with verdicts, `design`, `reconcile`, `evolve`) — the store is single-writer (§8), and extraction additionally holds a store-wide lock (a concurrent extract refuses `EXTRACT_LOCKED`, exit 2 — wait, never delete locks).
 
-Extract, design, and reconcile call the KaneAI service and consume credits; everything else is local and free.
+Extract, design, reconcile and evolve call the KaneAI service and consume credits; everything else is local and free.
 
 ## 2. The pause loop — exit 3 is a pause, NOT a failure
 
-**Scope: this rule applies to `context extract`/`context ingest`, `design tests`, and `maintain reconcile` (§11).** (For `run`/`testmd`/`testrun`, exit 3 still means timeout/cancelled.)
+**Scope: this rule applies to `context extract`/`context ingest`, `design tests`, `maintain reconcile` (§11) and, on 0.8.21+, `maintain evolve`.** (For `run`/`testmd`/`testrun`, exit 3 still means timeout/cancelled.)
 
 These commands take **`--mode agent`** — not `--agent`; they reject that flag, and a bare non-TTY invocation exits `2` asking for an explicit mode. In `--mode agent`, **every question pauses the run** (0.8.8+ — earlier CLIs auto-answered low/medium-risk questions with their recommended defaults and paused only on high risk):
 
@@ -227,7 +227,9 @@ Never `context ingest` the new version first — reconcile does its own re-inges
 - **`--from` takes URLs.** The same remote URLs ingest takes (§3): Jira/Confluence (0.7.2+), web pages (0.8.3+), Linear issues and documents (0.8.6+). `--source-id` is then optional — the URL carries its own id, and a contradicting `--source-id` refuses. Kind continuity holds both ways: a URL can't version a file-backed source and a file can't version a remote one — each refusal names the correct `--from`. A source ingested under a custom id (`--as`) is maintained by re-running that ingest with the same `--as`. The first reconcile of a Jira issue last ingested pre-0.7.2 may report the one-time upgrade re-version (§3) — not a content edit.
 - **One stream.** The re-extract child's events ride the reconcile stream itself, stamped `verb: "reconcile"` — parse per `references/assurance-parsing.md`.
 
-For staleness that arrived outside a reconcile, `kane-cli maintain evolve` re-designs a use-case — it is interactive-only (the blast-radius confirmation is the point); suggest the user run it in a terminal rather than scripting around it.
+For staleness that arrived outside a reconcile, `kane-cli maintain evolve <ref>` re-designs the parent use-case of the entity you name (`--from-stale` takes every use-case with stale designs). Give a `<ref>` or `--from-stale`, never both. A fresh target exits `2` unless you pass `--because "<reason>"`, and a use-case that was never designed exits `2` too (run `design tests` first). In a terminal evolve states the blast radius and asks.
+
+*(0.8.21+)* `kane-cli maintain evolve <ref> --mode agent` puts that question on the stream. A call on a stale target with no answer ends paused, exit `3`: `evolve_target` carries the blast radius (`use_case`, the `pairs` it affects, `because?`), then `evolve_paused` carries `pending_questions` (one per use-case, `id: "evolve:<use-case>"`, options `proceed` / `decline`), `resume` and `next[]` (two ready commands: proceed all, decline all), then `done{paused}`. Present the blast radius with the question, as with any pause (the pause loop above). Answer on the next call with `--answer evolve:<use-case>=1` (or `=proceed`) or `--answer evolve:<use-case>=2` (or `=decline`), repeatable; `--answer` needs `--mode agent`, and the resume command keeps `--because`. Nothing runs until every question is answered. A partial set pauses again on the rest, and the `next` commands then carry the answers already given, so a "decline the rest" command still re-designs what was answered proceed: read a `next` command before running it. On proceed, the design run's own events arrive between `child_start` and `child_end` stamped `verb: "design"`. After a clean design run comes `evolve_diff` (superseded, minted, retained, criteria whose tests moved). A design session that pauses arrives as its own `session_paused`: resume that session, then run evolve again for the diff. `done.next[]` carries every paused session's resume, all of them, whatever the exit code. In a `--from-stale` batch every use-case runs whatever the earlier ones did, and a declined or never-designed one is reported as `evolve_skipped`. Schema: `references/assurance-parsing.md`. On a CLI before 0.8.21 evolve has no `--mode`: suggest the user run it in a terminal rather than scripting around it.
 
 ## Sharing a context store
 

.agents/skills/kane-cli/references/testrun.md

@@ -15,7 +15,7 @@
 ## Command
 
 ```bash
-kane-cli testrun run [paths...] [flags] < /dev/null   # NDJSON only when stdin is not a TTY: every line you write ends in < /dev/null — there is NO --agent flag on testrun
+kane-cli testrun run [paths...] [flags] < /dev/null   # NDJSON when stdin is not a TTY: end every line in < /dev/null (0.8.21+ also takes --agent)
 ```
 
 `[paths...]` is optional — omit it to auto-discover every `*_test.md` under the cwd. Explicit paths must end in `_test.md`.
@@ -165,7 +165,7 @@ Local suites containing any mobile member require `--parallel 1`; larger values
 
 Healing is enabled by default (three shrinking replay windows, then re-authoring of authorable steps). `--no-adaptive-heal` disables it. Retired `--retry`/`--retry-count` only print a notice and have no effect. Replay-only recorded steps retain their recordings even during healing.
 
-NDJSON selection uses stdin, not stdout: every `kane-cli testrun run` line ends in `< /dev/null` (bash and zsh on macOS, Linux and Git Bash; `< NUL` in cmd.exe; from PowerShell run it through cmd: `cmd /c "kane-cli testrun run … < NUL"`). Check the first stdout line: on 0.8.17+ it is `{"type":"stream_start"…}`. A prose plan there instead means the CLI is in terminal mode: it prints the human view and, after a real run, opens an evidence table that waits until `q` or Esc, so the process never exits on its own. Stop it and rerun with the redirect. An empty stdout with a message on stderr is a usage error: read it. Dry-run validates a plan, not runtime authentication or browser/device readiness. Always observe process exit, including paths without a normal completion event.
+NDJSON selection uses stdin, not stdout (on 0.8.21+ `--agent` selects the same stream): every `kane-cli testrun run` line ends in `< /dev/null` (bash and zsh on macOS, Linux and Git Bash; `< NUL` in cmd.exe; from PowerShell run it through cmd: `cmd /c "kane-cli testrun run … < NUL"`). Check the first stdout line: on 0.8.17+ it is `{"type":"stream_start"…}`. A prose plan there instead means the CLI is in terminal mode: it prints the human view and, after a real run, opens an evidence table that waits until `q` or Esc, so the process never exits on its own. Stop it and rerun with the redirect. An empty stdout with a message on stderr is a usage error: read it. Dry-run validates a plan, not runtime authentication or browser/device readiness. Always observe process exit, including paths without a normal completion event.
 
 ### Remote behavior still requiring verification