@evo-hq/pi-evo 0.5.2 → 0.6.0-alpha.1

package/README.md

@@ -25,6 +25,8 @@ skill needs one to run multiple experiments per round.
 | `skills/discover/` | First-run setup: explore repo, propose optimization dimensions, build benchmark, run first experiment |
 | `skills/optimize/` | The search loop: parallel subagents form hypotheses, edit, get scored, frontier picks next branch |
 | `skills/subagent/` | Per-experiment brief contract for the optimize round's fanout |
+| `skills/report/` | Terminal score chart mirroring the dashboard scatter plot |
+| `skills/ship/` | Distill the best valid experiment into a clean mergeable change |
 | `skills/infra-setup/` | Provider matrix for remote-sandbox backends (Modal, E2B, Daytona, etc.) |
 
 ## Versioning

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@evo-hq/pi-evo",
-  "version": "0.5.2",
+  "version": "0.6.0-alpha.1",
   "description": "Evo plugin for pi-coding-agent: optimize/discover/subagent skills + mid-run inject extension.",
   "publishConfig": {
     "access": "public"

package/skills/discover/SKILL.md

@@ -2,7 +2,7 @@
 name: discover
 description: Initialize evo for the current repository by exploring the codebase, proposing unexplored optimization dimensions, constructing the benchmark inside a baseline worktree, and running the first experiment. Use when the user invokes /evo:discover, mentions setting up evo, wants to instrument a codebase for autonomous optimization, or asks to start a new evo run on a project.
 argument-hint: <optional context about what to optimize>
-evo_version: 0.5.2
+evo_version: 0.6.0-alpha.1
 ---
 
 # Discover
@@ -25,6 +25,9 @@ evo plugin
 │   │   ├── evo:optimize       after discover commits the baseline -- drives the loop.
 │   │   │                      Args: subagents=N (read sizing-the-round FIRST),
 │   │   │                            autonomous, subagents-only, budget=N, stall=N
+│   │   ├── evo:ship           after the loop stops -- distills the best valid
+│   │   │                      experiment into a mergeable change (PR if remote,
+│   │   │                      else merge) + a mergeability report
 │   │   ├── evo:finetuning     task is finetuning / post-training / training a model
 │   │   └── evo:infra-setup    need a remote backend, pooled workspaces, lease/slot
 │   │                          management, or specific provider auth/setup
@@ -116,20 +119,20 @@ evo --version
 The output must be exactly:
 
 ```
-evo-hq-cli 0.5.2
+evo-hq-cli 0.6.0-alpha.1
 ```
 
 Three outcomes:
 
 1. **Matches exactly** — continue to step 1.
 2. **Reports a different version** (`evo-hq-cli 0.4.2`, etc.) — the host refetched a newer/older skill bundle than the CLI on PATH. Drift breaks skills silently. Stop and tell the user:
-   > Your installed evo CLI is on a different version than this skill (`0.5.2`). Run:
+   > Your installed evo CLI is on a different version than this skill (`0.6.0-alpha.1`). Run:
    > ```
-   > uv tool install --force evo-hq-cli==0.5.2
+   > uv tool install --force evo-hq-cli==0.6.0-alpha.1
    > ```
    > Then re-invoke this skill.
 3. **`command not found`, or reports a different package** (commonly `evo 1.x` — the unrelated SLAM tool) — the CLI isn't installed. Tell the user:
-   > `evo-hq-cli` isn't on your PATH. Install it: `uv tool install evo-hq-cli==0.5.2` (or `pipx install evo-hq-cli==0.5.2`). Then re-invoke this skill.
+   > `evo-hq-cli` isn't on your PATH. Install it: `uv tool install evo-hq-cli==0.6.0-alpha.1` (or `pipx install evo-hq-cli==0.6.0-alpha.1`). Then re-invoke this skill.
 
 Do not try to auto-install. Host sandbox + network policy may block it; leaving the install as a user action keeps failure modes clear.
 
@@ -519,7 +522,39 @@ Document:
 - Benchmark gaming risks identified during the Goodhart check
 - Future experiment candidates (the non-picked dimensions from step 3)
 
-## 13. Report to the user
+## 13. Report public-safe use case telemetry
+
+Call the telemetry helper with a concrete but sanitized use-case summary. This
+command is globally disabled when the user runs `evo telemetry off`; do not
+branch on that yourself.
+
+Write one short sentence that captures: workload/system shape, optimization
+lever, and measured signal or failure mode. Add 3-6 lower-kebab-case tags for
+the workload, lever, metric/failure mode, runtime category, or benchmark source.
+Avoid filler-only tags like `optimization`, `benchmark`, or `codebase`.
+
+```bash
+evo telemetry usecase \
+  --description "<public-safe, concrete use case summary>" \
+  --tag <tag> --tag <tag> --tag <tag>
+```
+
+Privacy rule: do not include repo names, company names, customer names, file
+paths, benchmark commands, prompt text, task examples, secrets, URLs, internal
+system names, environment names, raw error logs, or exact dataset/item names.
+Generalize private nouns instead of deleting useful signal: "internal billing
+agent" becomes "workflow agent"; "Acme support router" becomes "support-style
+routing agent".
+
+Good example:
+
+```bash
+evo telemetry usecase \
+  --description "Optimizing a tool-calling coding agent for higher task pass rate by tuning planner/retry behavior against an existing per-task eval." \
+  --tag coding-agent --tag tool-calling --tag retry-policy --tag pass-rate --tag existing-eval
+```
+
+## 14. Report to the user
 
 End the skill by reporting in chat:
 

package/skills/infra-setup/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: infra-setup
 description: Non-user-invocable provider/setup reference for evo backend switching, prerequisite checks, and auth/install guidance.
-evo_version: 0.5.2
+evo_version: 0.6.0-alpha.1
 ---
 
 # Infra Setup

package/skills/optimize/SKILL.md

@@ -2,7 +2,7 @@
 name: optimize
 description: Drive structured autoresearch iteration after evo:discover and the baseline commit -- scan-subagent cross-cutting analysis between rounds, frontier-based parent selection, ideator dispatch on stall, verifier pre/post hooks, annotation discipline. Width is set via subagents=N (1 for serial workloads, larger for parallel); the loop's structural value applies at any width.
 argument-hint: "[subagents=N] [budget=N] [stall=N]"
-evo_version: 0.5.2
+evo_version: 0.6.0-alpha.1
 ---
 
 Run the `evo` optimization loop. Each round, the orchestrator writes structured briefs and spawns subagents that execute within them. Each subagent is semi-autonomous: it reads the pointer traces, forms the concrete edit, runs experiments, and can iterate within its branch. Runs until interrupted or the stall limit is reached.
@@ -102,17 +102,17 @@ evo defaults get subagents-only --json
 
 As your **very first actions, before the loop**, resolve each and arm it: run `evo autonomous on` / `evo subagents-only on` when it resolves on, or `evo autonomous off` / `evo subagents-only off` when an explicit instruction or stored default turned it off. If a behavior resolves off — whether from the user's instruction this run or a stored default — say so in your opening message (e.g. "autonomous off — running one round at a time, as you asked") so it's never invisible.
 
-**Orchestrator driver.** evo drives the loop two ways: a deterministic **dynamic workflow** (Claude Code only) or the **prose loop** below (every host). **On Claude Code the workflow is the DEFAULT — use it whenever it's available.** Resolve which as part of your very first actions:
+**Orchestrator driver.** evo drives the loop two ways: the **prose loop** below (every host) or a deterministic **dynamic workflow** (Claude Code only, opt-in). **The prose loop is the default everywhere; the workflow is used only when explicitly enabled** (`evo config set default-orchestrator workflow`). Resolve which as part of your very first actions:
 
 1. `evo host show` — the workflow driver requires `claude-code`. If it prints `<not set>` (a pre-host workspace), determine your actual runtime from your own context (system prompt, env such as `CLAUDECODE=1`, self-identity): **only if you are genuinely Claude Code**, do the one-time host migration now (`evo host set claude-code`) and continue; if you are any other runtime, do NOT stamp the host here — leave it for Step 0.1 and use the prose loop.
-2. `evo config get default-orchestrator` — `prose` is an explicit **opt-out** (honor it: use the prose loop). `workflow` **or unset** resolves to the workflow driver on Claude Code. An explicit user instruction this run still wins.
+2. `evo config get default-orchestrator` — `workflow` is an explicit **opt-in** (use the workflow driver on Claude Code). `prose` **or unset** resolves to the prose loop. An explicit user instruction this run still wins.
 
-**Use the workflow** when host is `claude-code`, the value is not explicitly `prose`, AND the **Workflow tool is actually present in your available tools this session** — this is the default path, not opt-in. The availability check is load-bearing: **older Claude Code builds do not ship the Workflow tool**, so verify it's really in your toolset; do not assume it exists from the host alone. When (and only when) you will actually launch it, FIRST persist the choice so the rest of evo agrees (`evo config get` reflects it, and the autonomous stop-nudge auto-suppresses under the workflow): run `evo config set default-orchestrator workflow`. Then launch it once — do NOT drive the loop turn-by-turn:
+**Use the workflow** only when `default-orchestrator` is explicitly `workflow`, host is `claude-code`, AND the **Workflow tool is actually present in your available tools this session** — it is opt-in, never the default. The availability check is load-bearing: **older Claude Code builds do not ship the Workflow tool**, so verify it's really in your toolset; do not assume it exists from the host alone. Reaching here means `default-orchestrator=workflow` is explicitly set (the opt-in trigger), so the autonomous stop-nudge is auto-suppressed under the workflow. Launch it once, do NOT drive the loop turn-by-turn:
 
 - Call the **Workflow** tool with `scriptPath: ${CLAUDE_PLUGIN_ROOT}/skills/optimize/workflows/evo-optimize.js` and `args: {pluginRoot: "${CLAUDE_PLUGIN_ROOT}", subagents: <N>, budget: <N>, stall: <N>}`, using the round sizing you resolved above. **Pass all four keys explicitly — never omit one.** For `stall`, use the user's `/optimize stall=N` override if given, else the default 5. (The workflow's stop condition is the stall limit, so a dropped `stall` silently reverts it to 5.)
 - Report the returned `runId` and tell the user to watch progress with `/workflows`. The workflow runs the round loop itself (orient → mandatory scan + cross-history axis check → ideators on stall/periodic → briefs → fan-out + verify → collect → frontier-select → stall) plus the concurrent meta controller; you do **not** execute "The Loop" section below, and you do **not** need autonomous mode (the workflow self-drives; its stall limit is the stop).
 
-Use **The Loop** below only when the workflow can't drive: host is not `claude-code`, `default-orchestrator` is explicitly `prose`, or the Workflow tool is unavailable (e.g. an older Claude Code build). The workflow is only an execution strategy over the same `evo` CLI; gates, frontier, dashboard, and recovery are identical either way.
+Use **The Loop** below by default — it is the prose driver on every host, and the path whenever the workflow is not explicitly enabled (`default-orchestrator` unset or `prose`), the host is not `claude-code`, or the Workflow tool is unavailable (e.g. an older Claude Code build). The workflow is only an execution strategy over the same `evo` CLI; gates, frontier, dashboard, and recovery are identical either way.
 
 **Reconcile config when you fall back to prose.** The stop-nudge that drives the prose loop is auto-suppressed whenever `default-orchestrator` is `workflow`. So if you fall back to the prose loop on Claude Code because the Workflow tool isn't available (older build) while `default-orchestrator` is still `workflow` from a prior run, you MUST set it back — `evo config set default-orchestrator prose` — and arm autonomous as usual. Otherwise the prose loop's stop-nudge stays suppressed and the run stalls after one round. Invariant to preserve: `default-orchestrator=workflow` in config iff the workflow is actually the driver this run.
 
@@ -331,16 +331,18 @@ After all subagents complete:
 
 **Cross-cut the round's evaluated nodes.** Before moving on, read `experiments/<id>/attempts/NNN/outcome.json` for each evaluated node from this round. The structured `gates[]` entries and `benchmark.result` let you spot shared failure modes the subagent summaries may have glossed over (e.g., three different subagents produced evaluated nodes whose gate_failures all included `refund_flow` -- that's a structural constraint the next round must confront, not three independent bad hypotheses).
 
-Prune dead branches where 3+ children all regressed:
+Prune branches you have decided are exhausted:
   ```bash
-  evo prune <exp_id> --reason "exhausted: N children all regressed"
+  evo prune <exp_id> --exhausted --reason "exhausted: <why>"
   ```
 
-`evo prune` accepts `committed` or `evaluated` nodes. Use it when you want
-to mark a lineage exhausted while preserving the result for later review or
-reference. Prune keeps the git commit alive (anchored at `refs/evo-anchor/<run>/<exp>`)
-so the node can be restored if needed. **Never `evo discard` a committed
-node** — it would orphan the branch ref and risk losing the commit.
+`evo prune` accepts `committed` or `evaluated` nodes:
+- `--exhausted` (default/legacy): stop branching here; the result still counts.
+- `--invalid`: this result is wrong; exclude it and descendants from best/frontier.
+- `--yes`: required only with `--invalid` on the current best valid spine.
+
+Use `--invalid --yes` when you have proven a best-spine result or ancestor is
+wrong. **Never `evo discard` a committed node** -- prune preserves its commit.
 
 If a previously-pruned (or discarded-then-restored) node is worth revisiting:
   ```bash
@@ -444,18 +446,49 @@ Proposals are advisory, not mandatory. If none look better than what step 3's sc
 - User hasn't interrupted
 - Score hasn't reached the theoretical maximum
 
+To continue, go back to step 1.
+
 **Stop** if:
 - Stall counter >= stall limit (N consecutive rounds with no improvement)
 - Score reached theoretical maximum (1.0 for max metric, 0.0 for min metric)
 - User interrupted
 
-On stop, print a final summary:
+On stop, the loop is done -- do not go back to step 1. Print a final summary:
 - Best score achieved and experiment ID
 - Total experiments run across all rounds
 - The winning diff: `evo diff <best_exp_id>`
 - Suggested next steps if the score hasn't converged
+- **How to land it:** point the user at `/evo:ship` to turn the winning
+  experiment into a mergeable change (a PR when the repo has a remote, else a
+  merge into the working branch). The raw winning diff is not the artifact to
+  merge by hand -- `/evo:ship` distills it to the minimal clean change and
+  attaches a mergeability report. Mention this whenever the run produced a
+  committed experiment that beats the baseline.
+
+### 8. Report evo-side feedback when evo itself went wrong
+
+Use feedback for evo product/orchestration issues, not for ordinary bad
+experiments. Good triggers: confusing CLI behavior, subagent handoff failures,
+workflow/meta-controller mistakes, recovery that failed, remote backend handling
+that was hard to diagnose, or an evo policy/gate that blocked the wrong thing.
+The command is anonymous and no-ops when telemetry is off; do not branch on that.
+
+Keep the report public-safe but actionable enough for the evo backend team to
+reproduce the case. Include the phase, what you expected evo to do, what it did,
+and a generic repro shape. Do not include repo names, company names, file paths,
+commands, prompt text, raw logs, URLs, secrets, dataset names, or exact task
+examples.
 
-Go back to step 1.
+```bash
+evo telemetry feedback \
+  --kind orchestration \
+  --phase optimize \
+  --summary "Subagent completed but the orchestrator did not collect its evaluated result before writing the next round briefs." \
+  --expected "Round collection should wait for all dispatched subagents or clearly report the missing one." \
+  --actual "The next round was planned from partial results, leaving one evaluated node out of the pattern scan." \
+  --repro "Run optimize with multiple subagents on a workspace where one branch finishes after the first completion notification." \
+  --tag optimize-loop --tag subagent-handoff --tag collection
+```
 
 ## Polling discipline
 

package/skills/optimize/workflows/evo-optimize.js

@@ -553,6 +553,7 @@ function metaPrompt(ctx, intervalS, reported, journal) {
     '- Dead direction / ignored mechanism: annotations repeatedly naming a mechanism the recent work ignores, or a direction that keeps regressing. BRIEF HINT.',
     '- Heading toward failure (STOP): an in-flight experiment that is CLEARLY doomed or wasting the budget — a divergent / NaN / flatlined progress metric; projected completion beyond the remaining time budget; or a known-fatal signature (e.g. output the scorer cannot parse; a silent resource mis-placement that tanks throughput with no error; a corrupt input/format that invalidates the result). HIGH PRECISION ONLY: default to NOT stopping — recommend a STOP only with concrete evidence that finishing is wasted, and only for an experiment still `active`. Emit a stop with: expId; failureClass (build = the build/produce step is broken; eval = artifact is fine but scoring/serving is wrong; hypothesis = it runs but won\'t help); reason (the diagnosis + the evidence you saw); fixHint (what the NEXT experiment must change).',
     'For STOPs you stay READ-ONLY: do NOT run `evo abort` / `evo discard` yourself. A gated enforcer acts on each stop — it aborts the run + its subprocess tree, annotates your diagnosis (so it outlives the worktree and feeds the next round), and discards with the failureClass so the partial artifact is preserved. A STOP is a diagnosed, recoverable stop, never a silent kill.',
+    'If you observe an evo workflow/meta-controller defect (missed collection, wrong prompt handoff, recovery confusion, bad stop/enforcer behavior), you MAY run `evo telemetry feedback --kind workflow --phase meta ...` with public-safe summary/expected/actual/repro/tags before returning. This is anonymous and no-ops when telemetry is off. Do NOT report ordinary bad experiments, raw logs, paths, commands, repo names, URLs, secrets, or prompt text.',
     '',
     'HARNESS CONTROL (your distinctive power): you may restructure the optimize workflow itself, live, when you judge it will help — edits apply directly (free will) and take effect next round. Current harness state: ' + JSON.stringify(harnessSummary()) + '.',
     'harnessEdits ops: (1) set-knob {knob: width|budget|stall|ideateEvery|ideateStall, value} — retune the loop (widen the round, deepen branches, change the stall limit or ideation cadence). (2) toggle-phase {phaseName: scan|ideate, enabled} — turn a phase off/on (e.g. skip scan when traces are uninformative; force ideation early). (3) set-prompt {target: state|scan|aggregate|brief|implement|run|ideator|collect|preverify|audit, mode: append|replace, text} — edit the prompt that step uses. Appends ACCUMULATE as standing directives (the current ones are visible in the harness state above — do not re-add them); replace swaps the base wholesale. Use preverify/audit to harden the verifier when you spot a cheat pattern the audit missed. (4) inject-step {at: before-scan|after-scan|before-brief|after-collect, text, label} — add an extra agent step at that seam each round. Every edit needs a rationale citing the evidence.',

package/skills/report/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: report
 description: Print the dashboard's dot chart (score over experiment order, status colors, best-path stair) inline in the terminal for every run in the workspace. Use when the user invokes /evo:report, asks for a quick score chart without opening the dashboard, or wants the scatter plot in chat output.
-evo_version: 0.5.2
+evo_version: 0.6.0-alpha.1
 ---
 
 # Report
@@ -13,10 +13,10 @@ Render the dashboard's scatter plot as a colored terminal block, one chart per r
 Mirrors the web dashboard's score scatter (left rail of `evo dashboard`):
 
 - X = experiment creation order, Y = score
-- Dot color by status: green = committed, red = failed, purple = active, grey = pending / evaluated / discarded / pruned
-- ★ marks the current best committed experiment
+- Dot color by status: green = committed valid result, red = failed, purple = active, grey = pending / evaluated / discarded / pruned
+- ★ marks the current best valid committed-result experiment. `pruned` with `prune_kind=exhausted` can still be best; `prune_kind=invalid` and its descendants cannot.
 - Yellow ring on dots that sit on the best-path spine (root → best)
-- Yellow stair line traces cumulative-best across committed experiments
+- Yellow stair line traces cumulative-best across valid committed-result experiments
 - ○ at the baseline for experiments that have no score yet (active / pending)
 
 Every run in the workspace is rendered, stacked top-to-bottom, with a header line showing `run_id · target · metric`.

package/skills/ship/SKILL.md

@@ -0,0 +1,140 @@
+---
+name: ship
+description: Land the winning experiment from an evo run as a clean, mergeable change -- open a PR when the repo has a remote, otherwise merge into the working branch. Distills the best-scoring experiment down to the minimal diff that reproduces its behaviour, shaped for the qualities a maintainer merges on (scope discipline, test integrity, style adherence), then attaches an advisory mergeability report. Use when the user invokes /evo:ship, asks to land/merge/ship the best result, or wants to turn a finished optimization into a pull request.
+evo_version: 0.6.0-alpha.1
+---
+
+# Ship
+
+Turn a finished evo run into a change a maintainer would merge.
+
+The optimize loop leaves a tree of committed experiments. The winning worktree
+diff is not mergeable as-is: it carries debug prints, search-process churn,
+over-broad edits, and sometimes a test that was relaxed to clear a gate. Shipping
+is the step that re-derives the *minimal clean change* reproducing the winning
+behaviour, lands it the way the repo expects (PR or merge), and reports how
+mergeable it is.
+
+Correctness is the floor, not the goal. The score says the behaviour works; this
+skill decides whether the *diff* is fit to merge.
+
+## Invocation
+
+```bash
+/evo:ship            # ship the auto-selected winner
+/evo:ship exp_0042   # ship a specific experiment instead
+```
+
+## Stage 1 -- Select the winner
+
+Pick the experiment to ship, then confirm it with the user before touching their
+tree.
+
+```bash
+evo status    # current best valid score + counts
+evo report    # top valid experiments table + score chart
+```
+
+- The default winner is the highest-scoring valid result in the graph history,
+  not the frontier. `evo frontier` is for choosing where to branch next; it can
+  exclude an exhausted branch whose score is still the right thing to ship. An
+  explicit `exp_id` argument overrides auto-selection.
+- A shippable winner must be valid: `committed`, or `pruned` with
+  `prune_kind=exhausted`, with a commit and score, no `gate_result === false`,
+  and no invalid-pruned ancestor. Never select `discarded`, `failed`, `active`,
+  `evaluated`, legacy-pruned nodes with no `prune_kind`, `prune_kind=invalid`, or
+  descendants of invalid-pruned nodes. If no valid candidate exists, stop and
+  report why nothing is safe to ship.
+- Resolve the run's root (baseline) node, then show the cumulative change:
+  ```bash
+  evo diff <root_id> <winner_id>   # target-scoped cumulative diff, baseline -> winner
+  ```
+  For changes outside the benchmark target, diff the commits directly
+  (`git diff <baseline_commit> <winner_commit>`); each node carries `.commit`.
+- Present a one-screen summary: winner id, score baseline -> winner (delta),
+  the winning hypothesis, and a diffstat. Get a go before proceeding.
+
+## Stage 2 -- Distill to a mergeable change
+
+Work on a fresh branch off the user's current HEAD, not in the experiment
+worktree. Re-derive the change so it stands on its own:
+
+- **Scope restraint.** Keep only the files and lines the behaviour needs. Drop
+  experiment scaffolding, debug logging, commented-out attempts, and churn the
+  search introduced and then abandoned. Smaller, local diffs merge; sprawl does
+  not.
+- **Test integrity.** If the search weakened, skipped, or deleted a test to clear
+  a gate, restore it. New behaviour that changes outputs needs a test that
+  covers it. Never ship a green benchmark that rode on a loosened test -- call it
+  out instead.
+- **Mechanical cleanliness.** Match the repo's formatter and linter. No stray
+  whitespace, no reordered imports unless the repo does that.
+- **Codebase adherence.** Match surrounding naming, error handling, and structure.
+  The diff should read like the file it lands in.
+
+Then confirm the behaviour survived the distillation:
+
+```bash
+evo run <winner_id> --check    # or the project's benchmark / test command
+```
+
+If the distilled change no longer reproduces the winning score, do not paper over
+it -- report the gap (which part of the experiment diff was load-bearing) and let
+the user decide. Best-effort means honest about what could not be cleaned up, not
+silently shipping the raw worktree.
+
+## Stage 3 -- Land
+
+Detect how the repo expects changes to arrive:
+
+```bash
+git remote -v
+```
+
+- **Remote present** -> open a pull request. Commit the distilled change on its
+  branch, push, and `gh pr create` with the mergeability report (Stage 4) as the
+  body. Do not push or open the PR without the user's go.
+- **No remote** -> merge the distilled change into the user's working branch as a
+  single clean commit. Do not force, do not rewrite existing history.
+
+The landed commit message carries provenance: the winning experiment id, the
+score delta, and the one-line hypothesis. State what changed and why it is safe;
+do not narrate the search process.
+
+## Stage 4 -- Mergeability report (advisory)
+
+Always produce the report. It never blocks the merge -- it tells the user, and a
+future reviewer, how mergeable the change is across the axes a maintainer judges
+on:
+
+- **Technique** -- what the change actually does to move the score, named
+  concretely (the algorithm, data structure, or mechanism), not the search
+  story. Distilled from the winning hypothesis: "replaced the O(n^2) dedup with a
+  hash set", not "exp_0042 improved throughput". This is what a reviewer reads
+  first.
+- **Behavioural correctness** -- score baseline -> shipped (delta); benchmark
+  status after distillation.
+- **Regression safety** -- full test suite result on the distilled change.
+- **Scope** -- files touched, diff size, whether the change stays local.
+- **Test correctness** -- explicit yes/no on whether any test was modified,
+  weakened, or removed, with detail; whether new behaviour is covered.
+- **Mechanical cleanliness** -- formatter / linter status.
+- **Codebase adherence** -- a note on style/convention fit.
+
+Lead with a plain-language summary: what changed and why it is safe to merge. On
+a remote repo this is the PR body. With no remote, print it and save it alongside
+the run so the user can paste it into a review later.
+
+## Guardrails (firm)
+
+Everything above is method you can adapt to the repo. These are not:
+
+- Never weaken, skip, or delete a test to make the change land. If the experiment
+  did, restore it and report it.
+- Never ship invalid-pruned, legacy-pruned, discarded, failed, active,
+  evaluated, gate-failed, or invalid-lineage nodes. Only exhausted pruned nodes
+  remain normal ship candidates.
+- Never push or open a PR without the user's explicit go.
+- Never rewrite or force-overwrite existing history on the user's branch.
+- Never ship the raw experiment worktree diff as-is when distillation failed --
+  report the gap instead.

package/skills/subagent/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: subagent
 description: Protocol that evo optimization subagents follow when dispatched from /optimize. Auto-loaded by spawned subagents via their host's skill loader. The orchestrator may also invoke this skill to understand the brief shape its dispatched subagents expect + what they're required to emit -- useful when writing briefs or debugging a subagent's behavior.
-evo_version: 0.5.2
+evo_version: 0.6.0-alpha.1
 ---
 
 # Evo Subagent Protocol
@@ -335,6 +335,29 @@ Continue if budget remains AND (last outcome was committed, OR you have a meanin
 
 Stop if budget exhausted, infra failure, or you've exhausted variations with no improvement.
 
+### 9. Report evo-side feedback when evo itself blocked you
+
+Use feedback for evo product/orchestration issues, not for ordinary bad
+experiments. Good triggers: confusing `evo run` behavior, remote workspace
+commands that were hard to recover from, verifier handoff problems, missing
+state that prevented you from following the brief, or a policy/gate that blocked
+the wrong thing. The command is anonymous and no-ops when telemetry is off.
+
+Keep it public-safe and reproducible. Do not include repo names, company names,
+file paths, commands, prompt text, raw logs, URLs, secrets, dataset names, or
+exact task examples.
+
+```bash
+evo telemetry feedback \
+  --kind orchestration \
+  --phase subagent \
+  --summary "Remote experiment recovery was unclear after the run process detached." \
+  --expected "Re-running evo run should clearly say whether it resumed or needs a fresh experiment." \
+  --actual "The subagent could not tell whether the active attempt was recoverable." \
+  --repro "Use a remote backend, interrupt a long-running experiment, then ask a subagent to continue the same exp_id." \
+  --tag remote-backend --tag recovery --tag subagent
+```
+
 ## Enriching traces
 
 Check `.evo/meta.json` for `"instrumentation_mode"` (`"sdk"` or `"inline"`) to see which style the benchmark uses -- **stay consistent with that choice across iterations; do not flip styles mid-run.**
@@ -357,7 +380,8 @@ If your experiment needs an artifact that is slow to produce and stable across s
 
 - Do NOT run `evo init` or `evo reset`
 - `evo discard <your_exp_id> --reason "..."` is your explicit "abandon" action — use it for any *non-committed* node you've decided not to pursue further (pre-run realization, evaluated with a bad hypothesis, or unfixable infra failure). Discard deletes the worktree and branch; the node and its per-attempt artifacts stay in `.evo/` as a record of what was tried.
-- If `evo discard` errors with **"cannot discard committed node ... use prune"** — the experiment cleared the gate and improved the score. You shouldn't be discarding it. Don't fight the error; the orchestrator owns committed-lineage decisions via `evo prune`.
+- If `evo discard` errors with **"cannot discard committed node ... use prune"** — the experiment cleared the gate and improved the score. You shouldn't be discarding it. Don't fight the error; the orchestrator owns committed-lineage decisions via `evo prune --exhausted` or `evo prune --invalid`.
+- If you discover a committed result is invalid (bad score calculation, benchmark gaming, weakened/deleted tests, failed inherited gate, or failed repro), report the exact node and evidence. Do not discard it; the orchestrator should mark it with `evo prune <id> --invalid --reason "..."` and add `--yes` only if evo says the node is on the current best spine.
 - If `evo discard` errors with **"cannot discard active node ... pass --force"** — the run is still in flight. Wait for it to finish; don't `--force` unless you know what you're doing (the running process can still write a final outcome that contradicts the discard).
 - If `evo discard` errors with **"cannot discard ... has non-discarded children"** — sibling/child experiments depend on this node's parent reference. Discard or commit-and-prune those first.
 - Do NOT copy `.env` files, bake secrets into source, or hard-code local runtime paths. Runtime setup/env is configured by the orchestrator (`evo config runtime ...`, `evo env ...`) and injected into benchmark/gate processes. If a missing dependency, setup step, or key blocks evaluation, report setup failure.